Guia de API Key

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. Esta página cobre o ciclo de vida da chave: criar, listar, revogar e escolher escopos.

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). Uma API Key não gerencia outras API Keys: os endpoints de /v1/api-keys não aceitam autenticação por API Key.

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.

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"
  }'

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();

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"]

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

{
  "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"
  }
}

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.

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.

curl https://api.nuvia.ai/v1/api-keys \
  -H "Authorization: Bearer $NUVIA_USER_TOKEN"

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();

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"]

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.

cURL

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.

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.

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:

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.

Boas práticas de segurança

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.

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”.

Defina uma expiração

Use expiresAt para chaves de vida curta ou temporárias, reduzindo a janela de exposição caso a chave vaze.

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.

Primeiros passos

Guias

Criar uma API Key

Listar API Keys

Revogar uma API Key

Escopos disponíveis

Modelo de posse

Boas práticas de segurança

Próximos passos

Autenticação

Rate limits

​Criar uma API Key

​Listar API Keys

​Revogar uma API Key

​Escopos disponíveis

​Modelo de posse

​Boas práticas de segurança

​Próximos passos

Autenticação

Rate limits

Criar uma API Key

Listar API Keys

Revogar uma API Key

Escopos disponíveis

Modelo de posse

Boas práticas de segurança

Próximos passos