As API Keys são credenciais que permitem que sistemas externos se autentiquem na API da Nuvia em nome da sua empresa. Cada chave tem seus próprios escopos de permissão e pode ser revogada quando você quiser.
Antes de começar
-
Confirme que seu perfil tem acesso de administrador.
-
Tenha um local seguro para guardar o token, como um gerenciador de segredos. O token é exibido uma única vez, no momento da criação, depois disso não há como visualizá-lo novamente.
Acessar a página de API Keys
-
No Menu lateral, clique em nos 3 pontinhos ao lado do ícone de perfil
-
Clique na opção Configurações
-
No Menu lateral, clique em API Keys
A listagem mostra todas as API Keys da sua empresa, com nome, escopos, preview do token (os 4 últimos caracteres), data de criação, validade, último uso e status.
Criar uma nova API Key
-
Na página de API Keys, clique em Nova API Key.
-
Preencha o Nome, use algo descritivo que identifique a integração (ex.: “CRM Integration”, “Dashboard BI”).
-
Selecione os Escopos que esta chave poderá acessar (veja a lista completa na seção Escopos de permissão disponíveis, abaixo).
-
(Opcional) Defina uma Validade escolhendo uma data futura no calendário. Se deixar em branco, a chave não expira.
-
Clique em Criar API Key.
-
Clique em Copiar token para copiar o JWT para a área de transferência.
-
Guarde o token em um local seguro.
-
Clique em Fechar.
Escopos de permissão disponíveis
Cada escopo libera um conjunto de ações sobre um recurso da API. Você escolhe os escopos no momento da criação da chave.
| Recursos | Ações disponíveis |
|---|---|
| Agentes | Ler, Criar, Atualizar, Excluir |
| Contatos | Ler, Criar, Atualizar, Excluir |
| Conversas | Ler, Criar, Atualizar |
| Campanhas | Ler, Criar, Atualizar, Excluir |
| Mensagens | Ler, Enviar |
| Caixas de entrada | Ler, Criar, Atualizar, Excluir |
| Tabelas | Ler, Criar, Atualizar, Excluir |
| Tools de agente | Ler, Criar, Atualizar, Excluir |
| Follow-ups de agente | Ler, Criar, Atualizar, Excluir |
| Anotações de contato | Ler, Criar, Atualizar |
| Enrollments de campanha | Ler, Criar |
| Campos customizados | Ler, Atualizar valor |
| Base de conhecimento | Ler, Criar, Atualizar |
| Webhooks | Ler, Criar, Atualizar, Excluir |
| Busca | Consultar, Enriquecer e salvar |
| Busca LinkedIn | Consultar, Salvar |
| Enriquecimento | Consultar, Executar |
| Triggers de campanha | Disparar |
O que os escopos de Campos customizados liberam
Os escopos de Campos customizados servem para uma integração gravar valor em campos que já existem, não para criar ou apagar a definição do campo.
| Escopo | O que a chave pode fazer |
|---|---|
| Campos custom — Ler | Listar os campos personalizados da empresa (para descobrir o identificador de cada um) e listar as opções ativas de um campo de lista suspensa ou múltipla escolha |
| Campos custom — Atualizar valor | Gravar o valor de um campo personalizado em uma conversa, no contato dela ou na empresa do contato |
Ao gravar valor, vale saber:
-
O campo é identificado pelo slug (o identificador que aparece na listagem de campos), não pelo ID interno.
-
A conversa é obrigatória na chamada, mesmo quando o campo é de contato ou de empresa: é a partir da conversa que a Nuvia encontra o contato e a empresa.
-
Campos de texto, número e data recebem o valor direto. Campos de lista suspensa e múltipla escolha recebem o identificador da opção, que vem da listagem de opções do campo.
-
Valor fora das opções aceitas é recusado, e a resposta traz a lista dos valores válidos.
-
Campo ou conversa de outra empresa é recusado.
Disparar campanhas a partir de um CRM próprio (escopo Triggers de campanha)
O escopo Triggers de campanha — Disparar libera o endpoint que permite um CRM próprio ou uma automação (n8n, Zapier ou uma chamada direta à API) disparar campanhas na Nuvia a partir de eventos do seu CRM: contato criado ou atualizado, negócio (deal) criado ou atualizado e lead criado ou atualizado.
Use quando o seu CRM não é um dos integrados nativamente (HubSpot ou RD Station) e você quer que ele acione campanhas na Nuvia. A automação envia o contato (com telefone) e os dados do evento, e a Nuvia inscreve o contato nas campanhas configuradas.
Filtrar e buscar API Keys
Use os filtros no canto superior direito da página para alternar entre:
-
Ativas, chaves que podem autenticar requisições (visão padrão).
-
Revogadas, chaves desativadas permanentemente.
-
Todas, exibe ativas e revogadas.
Você também pode localizar uma chave pelo nome usando o campo de busca.
Revogar uma API Key
A revogação desativa a chave de forma permanente. Use quando uma integração for descontinuada, quando você for rotacionar credenciais ou quando houver suspeita de vazamento.
-
Na listagem, localize a API Key que deseja revogar.
-
Clique no menu de ações (⋮) à direita da linha.
-
Clique em Revogar.
-
No modal de confirmação, preencha a Justificativa (ex.: “integração descontinuada”, “key vazada”, “rotação de credenciais”).
-
Clique em Revogar API Key.
-
A chave deixa de autenticar requisições imediatamente.
Status de uma API Key
| Status | Cor na interface | O que significa |
|---|---|---|
| Ativa | Verde | A chave está funcionando e autentica requisições normalmente. |
| Expirada | Vermelho | A data de validade configurada já passou; a chave não autentica mais. Crie uma nova para continuar. |
| Revogada | Cinza | A chave foi desativada permanentemente por um usuário e não autentica mais. |