1. [Ajuda](https://nuvia.ai/docs) 2. [Configurações de Conta](https://nuvia.ai/docs/colecoes/19430666-configuracoes-de-conta) # Como gerenciar API Keys na Nuvia Crie, organize e revogue credenciais de API para conectar sistemas externos à Nuvia, com escopos de permissão granulares e revogação imediata a qualquer momento. Disponível em Todos os planos. Quem pode fazer Administradores da conta Atualizado em 9 de setembro de 2026 [Configurações de Conta](https://nuvia.ai/docs/colecoes/19430666-configuracoes-de-conta) 1. [Como ativar a verificação em duas etapas (MFA)](https://nuvia.ai/docs/artigos/18174510-como-ativar-a-verificacao-em-duas-etapas-mfa) 2. [Como marcar sua disponibilidade (Ausente ou Indisponível)](https://nuvia.ai/docs/artigos/18174522-como-marcar-sua-disponibilidade-ausente-ou-indisponivel) 3. [Como gerenciar API Keys na Nuvia](https://nuvia.ai/docs/artigos/15230128-como-gerenciar-api-keys-na-nuvia) 4. [Como desativar e reativar um usuário](https://nuvia.ai/docs/artigos/16497565-como-desativar-e-reativar-um-usuario) 5. [Segurança, privacidade e LGPD na Nuvia](https://nuvia.ai/docs/artigos/14576039-seguranca-privacidade-e-lgpd-na-nuvia) 6. [Como criar e gerenciar equipes na Nuvia](https://nuvia.ai/docs/artigos/15649230-como-criar-e-gerenciar-equipes-na-nuvia) Nesta página 1. Antes de começar 2. Acessar a página de API Keys 3. Criar uma nova API Key 4. Escopos de permissão disponíveis 5. O que os escopos de Campos customizados liberam 6. Disparar campanhas a partir de um CRM próprio (escopo Triggers de campanha) 7. Filtrar e buscar API Keys 8. Revogar uma API Key 9. Status de uma API Key **Nesta página9 seções** 1. Antes de começar 2. Acessar a página de API Keys 3. Criar uma nova API Key 4. Escopos de permissão disponíveis 5. O que os escopos de Campos customizados liberam 6. Disparar campanhas a partir de um CRM próprio (escopo Triggers de campanha) 7. Filtrar e buscar API Keys 8. Revogar uma API Key 9. Status de uma API Key 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 1. No **Menu lateral**, clique em nos 3 pontinhos ao lado do ícone de perfil 2. Clique na opção **Configurações** 3. 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 1. Na página de API Keys, clique em **Nova API Key**. 2. Preencha o **Nome**, use algo descritivo que identifique a integração (ex.: “CRM Integration”, “Dashboard BI”). 3. Selecione os **Escopos** que esta chave poderá acessar (veja a lista completa na seção **Escopos de permissão disponíveis**, abaixo). 4. (Opcional) Defina uma **Validade** escolhendo uma data futura no calendário. Se deixar em branco, a chave **não expira**. 5. Clique em **Criar API Key**. 6. Clique em **Copiar token** para copiar o JWT para a área de transferência. 7. Guarde o token em um local seguro. 8. Clique em **Fechar**. O token é exibido **apenas uma vez**. Depois de fechar o modal, não é possível visualizá-lo novamente, a única referência na listagem passa a ser o sufixo de 4 caracteres (coluna **Preview**). Se perder o token, será necessário revogar a chave e criar uma nova. **Dica:** Se você tentar fechar o modal sem copiar o token, a Nuvia exibe um aviso de confirmação. Volte e copie antes de prosseguir. ## 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. RecursosAçõ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 Importante os escopos são definidos na criação e não podem ser alterados depois. Se precisar de permissões diferentes, crie uma nova chave com os escopos desejados e revogue a anterior. ## 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. EscopoO 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 Importante criar, editar ou excluir a **definição** de um campo personalizado (e as opções dele) continua sendo ação de usuário logado na plataforma, com a permissão de Campos personalizados. Uma API Key não faz isso, mesmo com os dois escopos marcados. Por isso os escopos “Campos custom — Criar” e “Campos custom — Excluir”, que apareciam na lista sem nenhuma operação por trás, foram removidos. 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. Importante ao disparar por esse endpoint, o contato é localizado pelo **telefone** e o vínculo de CRM dele passa a apontar para a integração que fez o disparo. Se o contato já pertencia a outra integração (por exemplo, HubSpot), a sincronização anterior deixa de valer para ele. Use um telefone no formato internacional (E.164, ex.: +5511999999999). Dica para evitar disparos duplicados quando a sua automação repete a chamada, envie um **identificador de idempotência** — repetições dentro de 24h são ignoradas. ## 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. 1. Na listagem, localize a API Key que deseja revogar. 2. Clique no menu de ações (**⋮**) à direita da linha. 3. Clique em **Revogar**. 4. No modal de confirmação, preencha a **Justificativa** (ex.: “integração descontinuada”, “key vazada”, “rotação de credenciais”). 5. Clique em **Revogar API Key**. 6. A chave deixa de autenticar requisições imediatamente. Importante a revogação é **permanente e não pode ser desfeita**. A chave entra em uma blacklist e nenhum sistema que a utilize conseguirá mais se autenticar. Atualize o token no sistema externo **antes** de revogar a chave antiga. ## Status de uma API Key StatusCor na interfaceO 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. Nota Se a conta está no **período de teste (trial)** e o trial vence, toda API Key da empresa para de autenticar — mesmo aparecendo como **Ativa** na listagem e sem data de validade configurada. O bloqueio segue o **status da assinatura em tempo real**, não uma data gravada na chave: some automaticamente assim que a conta volta a ficar ativa (contratação do plano). ## Perguntas frequentes **Quantas API Keys posso criar por empresa?** Não há limite. Crie quantas forem necessárias. A recomendação é usar **uma chave por integração ou sistema externo**, o que facilita a gestão e a rastreabilidade. **Perdi o token JWT. Consigo recuperá-lo?** Não. Por segurança, a Nuvia não armazena o JWT completo. A única opção é revogar a chave atual e criar uma nova. Use o sufixo de 4 caracteres (coluna **Preview**) para identificar qual chave precisa ser substituída. **Posso editar os escopos de uma API Key existente?** Não. Os escopos são definidos no momento da criação e não podem ser alterados depois. Se precisar de escopos diferentes, crie uma nova chave com as permissões desejadas e revogue a anterior. **Os escopos “Campos custom — Criar” e “Campos custom — Excluir” desapareceram da lista. Onde foram?** Foram removidos porque não existia nenhuma operação de API por trás deles: eram escopos que podiam ser marcados e não liberavam nada. Criar e excluir campo personalizado (e as opções dele) é ação de usuário na plataforma, não de API Key. Se você tinha uma chave com esses escopos marcados, nada muda na prática — a integração nunca conseguiu criar ou excluir campo por eles. **Apareceram escopos novos de Base de conhecimento e Webhooks. São recursos novos?** Não. Esses endpoints já aceitavam API Key; o que faltava era a lista de escopos da tela mostrar isso, então ninguém sabia que podia pedir. Agora eles aparecem agrupados em **Base de conhecimento** e **Webhooks** na hora de criar a chave. O mesmo vale para os escopos de Tools de agente, Follow-ups de agente, Anotações de contato e Caixas de entrada — Excluir. **O que acontece com as requisições em andamento quando eu revogo uma chave?** A revogação é imediata: qualquer requisição que use o token revogado é rejeitada a partir daquele momento. Atualize o token no sistema externo antes de revogar a chave antiga. **A coluna “Último uso” não mostra data. O que significa?** Significa que a chave ainda não foi usada em nenhuma requisição desde a criação. A data é preenchida automaticamente após o primeiro uso. **Para que serve o escopo “Triggers de campanha”?** Ele libera o disparo de campanhas a partir de um CRM próprio ou de uma automação (n8n, Zapier ou chamada direta), sem depender das integrações nativas. Ao receber um evento (contato, negócio ou lead criado/atualizado), a Nuvia localiza o contato pelo telefone e o inscreve nas campanhas configuradas. Conceda esse escopo apenas à chave usada por essa automação. **API Key e a conexão via MCP são a mesma coisa?** Não. A **API Key** é uma credencial (token JWT) para integrações de sistema a sistema com a API da Nuvia. Já o **MCP** conecta aplicativos de IA (como Claude e Cursor) via autorização OAuth, com login na própria tela da Nuvia (sem gerar uma API Key). Use API Key para integrar servidores e sistemas; use MCP para conectar clientes de IA. **Minha integração parou de funcionar do nada, mas a chave aparece como Ativa. Por quê?** O motivo mais comum é o fim do período de teste (trial) da conta: enquanto o trial está vencido, nenhuma API Key da empresa autentica, independentemente do status mostrado na listagem ou da validade configurada. Contrate um plano para reativar a conta — o acesso da chave volta sozinho, sem precisar recriá-la. [AnteriorComo marcar sua disponibilidade (Ausente ou Indisponível)](https://nuvia.ai/docs/artigos/18174522-como-marcar-sua-disponibilidade-ausente-ou-indisponivel) [PróximoComo desativar e reativar um usuário](https://nuvia.ai/docs/artigos/16497565-como-desativar-e-reativar-um-usuario) Este artigo ajudou? ## Artigos relacionados - [Como conectar o WhatsApp na Nuvia](https://nuvia.ai/docs/artigos/14489425-como-conectar-o-whatsapp-na-nuvia) - [Como criar habilidades personalizadas para o agente de IA](https://nuvia.ai/docs/artigos/14590394-como-criar-habilidades-personalizadas-para-o-agente-de-ia) - [Referência das ferramentas MCP da Nuvia](https://nuvia.ai/docs/artigos/16074574-referencia-das-ferramentas-mcp-da-nuvia) - [O que a Nuvia sincroniza com o HubSpot e quando](https://nuvia.ai/docs/artigos/16473526-o-que-a-nuvia-sincroniza-com-o-hubspot-e-quando) [Configurações de Conta](https://nuvia.ai/docs/colecoes/19430666-configuracoes-de-conta) 1. [Como ativar a verificação em duas etapas (MFA)](https://nuvia.ai/docs/artigos/18174510-como-ativar-a-verificacao-em-duas-etapas-mfa) 2. [Como marcar sua disponibilidade (Ausente ou Indisponível)](https://nuvia.ai/docs/artigos/18174522-como-marcar-sua-disponibilidade-ausente-ou-indisponivel) 3. [Como gerenciar API Keys na Nuvia](https://nuvia.ai/docs/artigos/15230128-como-gerenciar-api-keys-na-nuvia) 4. [Como desativar e reativar um usuário](https://nuvia.ai/docs/artigos/16497565-como-desativar-e-reativar-um-usuario) 5. [Segurança, privacidade e LGPD na Nuvia](https://nuvia.ai/docs/artigos/14576039-seguranca-privacidade-e-lgpd-na-nuvia) 6. [Como criar e gerenciar equipes na Nuvia](https://nuvia.ai/docs/artigos/15649230-como-criar-e-gerenciar-equipes-na-nuvia) ## Ainda precisa de ajuda? Clientes falam com o suporte pelo chat dentro da plataforma. Ainda não é cliente? Fale com o nosso time. [Falar com o suporte na plataforma](https://app.nuvia.ai) [Ainda não sou cliente](https://nuvia.ai/contact) --- Source: https://nuvia.ai/docs/artigos/15230128-como-gerenciar-api-keys-na-nuvia