> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nuvia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia de API Key

> Como gerar, listar e revogar API Keys da Nuvia, e quais escopos existem

Uma API Key é o token que sua integração usa para autenticar na API da Nuvia. Para saber **como
enviar** a chave nas requisições, veja [Autenticação](/autenticacao). Esta página cobre o
**ciclo de vida** da chave: criar, listar, revogar e escolher escopos.

<Note>
  As API Keys são criadas e gerenciadas por um **usuário humano** autenticado com o token de login
  do aplicativo (JWT humano — veja [Autenticação](/autenticacao)). Uma API Key **não** gerencia
  outras API Keys: os endpoints de `/v1/api-keys` não aceitam autenticação por API Key.
</Note>

## Criar uma API Key

Envie um `POST /v1/api-keys` autenticado como usuário. O corpo aceita:

| Campo       | Tipo              | Obrigatório | Descrição                                                                  |
| ----------- | ----------------- | ----------- | -------------------------------------------------------------------------- |
| `name`      | string            | Sim         | Nome de identificação da chave (até 100 caracteres).                       |
| `scopes`    | string\[]         | Sim         | Lista de escopos no formato `<subject>:<action>` (veja o catálogo abaixo). |
| `expiresAt` | string (ISO 8601) | Não         | Data futura de expiração. Se omitido, a chave não expira por tempo.        |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.nuvia.ai/v1/api-keys \
    -H "Authorization: Bearer $NUVIA_USER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Integração de produção",
      "scopes": ["contacts:read", "messages:create"],
      "expiresAt": "2027-01-01T00:00:00.000Z"
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.nuvia.ai/v1/api-keys", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NUVIA_USER_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Integração de produção",
      scopes: ["contacts:read", "messages:create"],
      expiresAt: "2027-01-01T00:00:00.000Z",
    }),
  });

  const { accessToken, apiKey } = await res.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  res = requests.post(
      "https://api.nuvia.ai/v1/api-keys",
      headers={"Authorization": f"Bearer {os.environ['NUVIA_USER_TOKEN']}"},
      json={
          "name": "Integração de produção",
          "scopes": ["contacts:read", "messages:create"],
          "expiresAt": "2027-01-01T00:00:00.000Z",
      },
  )

  body = res.json()
  access_token = body["accessToken"]
  ```
</CodeGroup>

A resposta (`201`) traz o token em `accessToken` e os metadados da chave em `apiKey`:

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "apiKey": {
    "name": "Integração de produção",
    "scopes": ["contacts:read", "messages:create"],
    "status": "ACTIVE",
    "keyPreview": "...a1b2",
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }
}
```

<Warning>
  O valor completo do token aparece **uma única vez**, no campo `accessToken` da resposta de
  criação. A Nuvia **não armazena o token** e não há como recuperá-lo depois — só ficam guardados
  metadados e uma prévia (`keyPreview`, os últimos 4 caracteres). Copie e guarde o token com
  segurança nesse momento. Se você perder o token, revogue a chave e crie uma nova.
</Warning>

## Listar API Keys

`GET /v1/api-keys` retorna as chaves da sua empresa (com paginação `{ data, meta }`). A resposta
traz apenas metadados — nunca o token.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.nuvia.ai/v1/api-keys \
    -H "Authorization: Bearer $NUVIA_USER_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.nuvia.ai/v1/api-keys", {
    headers: { Authorization: `Bearer ${process.env.NUVIA_USER_TOKEN}` },
  });

  const { data, meta } = await res.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  res = requests.get(
      "https://api.nuvia.ai/v1/api-keys",
      headers={"Authorization": f"Bearer {os.environ['NUVIA_USER_TOKEN']}"},
  )

  data = res.json()["data"]
  ```
</CodeGroup>

## Revogar uma API Key

`DELETE /v1/api-keys/:id` revoga a chave imediatamente e responde `204 No Content`. A operação é
**idempotente** — revogar uma chave já revogada não causa erro. A chave precisa pertencer à sua
empresa.

```bash cURL theme={null}
curl -X DELETE https://api.nuvia.ai/v1/api-keys/652f1a9c8b3e4d0012a7f4c1 \
  -H "Authorization: Bearer $NUVIA_USER_TOKEN"
```

Uma vez revogada, a chave para de autenticar em qualquer requisição.

## Escopos disponíveis

Escopos seguem o formato `<subject>:<action>`. Ao criar uma chave, conceda **apenas** os escopos de
que a integração precisa. A tabela abaixo lista o catálogo disponível no painel, agrupado por
subject.

| Subject           | Ações                                   | O que o subject libera                                                      |
| ----------------- | --------------------------------------- | --------------------------------------------------------------------------- |
| `agents`          | `read` · `create` · `update` · `delete` | Agentes de IA: listar, criar, clonar e atualizar.                           |
| `contacts`        | `read` · `create` · `update` · `delete` | Contatos: gerenciar contatos e seus vínculos.                               |
| `conversations`   | `read` · `create` · `update`            | Conversas: listar e atualizar (atribuir agente, dono, prioridade, equipe).  |
| `campaigns`       | `read` · `create` · `update` · `delete` | Campanhas: gerenciar campanhas, ativação e analytics.                       |
| `messages`        | `read` · `create`                       | Mensagens: ler mensagens de uma conversa e enviar (texto, mídia, template). |
| `inboxes`         | `read` · `create` · `update`            | Inboxes: gerenciar caixas de entrada.                                       |
| `tables`          | `read` · `create` · `update` · `delete` | Tabelas e listas: gerenciar tabelas, colunas e exportações.                 |
| `knowledge-base`  | `read` · `create` · `update`            | Base de conhecimento: gerenciar itens de conhecimento.                      |
| `webhooks`        | `read` · `create` · `update` · `delete` | Webhooks: gerenciar configurações de webhook.                               |
| `search-v2`       | `read` · `create`                       | Busca de empresas e prospects (Brasil e global) e autocomplete.             |
| `linkedin-search` | `read` · `create`                       | Busca no LinkedIn: perfis, empresas e parâmetros.                           |
| `enrichment`      | `read` · `create`                       | Enriquecimento de contatos e consulta de elegibilidade/créditos.            |

<Note>
  O painel só oferece os escopos deste catálogo. Se um endpoint retornar `403` mesmo com uma chave
  válida, confirme que a chave foi criada com o escopo exigido por aquele endpoint.
</Note>

## Modelo de posse

Uma API Key pertence à **empresa** (o tenant), não ao usuário que a criou. O usuário criador é
registrado apenas para auditoria. Uma consequência importante:

<Warning>
  A chave **não é revogada automaticamente** quando o usuário que a criou é desativado ou removido
  da empresa — ela continua válida. Para encerrar o acesso de uma chave, **revogue-a explicitamente**
  com `DELETE /v1/api-keys/:id`.
</Warning>

## Boas práticas de segurança

<Steps>
  <Step title="Trate a chave como um segredo">
    A API Key é um Bearer token que dá acesso a tudo o que os seus escopos permitem. Guarde-a em
    variável de ambiente ou cofre de segredos — nunca no código-fonte nem no controle de versão.
  </Step>

  <Step title="Aplique o menor privilégio">
    Conceda somente os escopos necessários para a integração. Evite criar chaves com o catálogo
    inteiro "por precaução".
  </Step>

  <Step title="Defina uma expiração">
    Use `expiresAt` para chaves de vida curta ou temporárias, reduzindo a janela de exposição caso
    a chave vaze.
  </Step>

  <Step title="Revogue o que não usa">
    Revogue chaves antigas, de testes ou não utilizadas. Como a chave sobrevive à saída do usuário
    criador, a limpeza é responsabilidade da empresa.
  </Step>
</Steps>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="lock" href="/autenticacao">
    Como enviar a API Key nas requisições e entender os erros de auth.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/guias/rate-limits">
    Como a API trata limites de requisição hoje.
  </Card>
</CardGroup>