Gerar uma chave de API para sua certificadora
Um guia passo a passo para emitir um token de API com escopo para que uma certificadora externa acesse seus arquivos de evidência com segurança.
O que é uma chave de API de integração?
Uma integração é um token de API com escopo que permite a um serviço externo — como a certificadora que audita sua conformidade — acessar os arquivos de evidência da sua organização sem usar um login pessoal. Você decide exatamente o que cada token pode fazer e por quanto tempo ele dura.
Acesso com escopo
Cada chave concede apenas as permissões que você selecionar — nada além disso.
Prazo limitado
Defina uma expiração para que o acesso termine automaticamente quando a auditoria acabar.
Revogável
Desative uma chave a qualquer momento para cortar o acesso imediatamente.
Para quem é este guia?
Este guia é para administradores de organização que precisam dar a uma certificadora ou auditor externo acesso programático aos seus arquivos de evidência.
Antes de começar
A autenticação de dois fatores (2FA) está ativada na sua conta. Ela é obrigatória para criar uma chave de API — veja a seção abaixo para configurá-la.
Você é administrador da organização ou um membro com a permissão de Criar integração.
Suas chaves de criptografia estão desbloqueadas — necessário apenas se a certificadora precisar descriptografar arquivos (escopo files:decrypt).
Um canal seguro para entregar as credenciais à certificadora, como um gerenciador de senhas ou um cofre de segredos.
Clareza sobre quais escopos a certificadora precisa, para que você conceda o mínimo privilégio necessário.
Ative o 2FA antes de criar uma chave
Emitir uma chave de API é uma ação sensível, então a plataforma exige autenticação de dois fatores (2FA) na sua conta e pede a confirmação de um código sempre que você cria uma chave. Se você ainda não tem 2FA, configure-o uma única vez seguindo os passos abaixo.
O 2FA é obrigatório para criar uma chave de API
Sem o 2FA ativado, a ação Criar integração fica bloqueada. Ative-o uma vez na sua conta e você já estará pronto para emitir chaves.
- 1
Abra as configurações de segurança do seu perfil
Acesse seu perfil, abra a aba Segurança e clique em Ativar 2FA.
- 2
Confirme sua senha
Digite a senha atual da sua conta para autorizar a ativação da autenticação de dois fatores.
- 3
Adicione a conta ao seu aplicativo autenticador
Escaneie o QR code com um aplicativo autenticador (Google Authenticator, Authy, 1Password, Microsoft Authenticator, …) ou digite manualmente no app o segredo exibido.
- 4
Guarde seus códigos de backup
Guarde os códigos de backup de uso único em um local seguro. Eles permitem que você entre caso perca o acesso ao seu aplicativo autenticador.
- 5
Confirme o código de 6 dígitos
Digite o código de 6 dígitos atual do seu aplicativo autenticador para concluir a ativação do 2FA. Sua conta agora está protegida.
O que acontece a seguir
A partir daí, sempre que você criar ou rotacionar uma chave de API, aparece uma janela Verifique sua identidade — basta digitar o código de 6 dígitos atual do seu aplicativo autenticador para autorizar a ação.
Gerando a chave de API
- 1
Acesse as configurações da sua organização
Na plataforma, acesse as configurações da sua organização e abra a aba Integrações. É onde ficam listadas todas as chaves de API emitidas para a sua organização.
Configurações da organização com a aba Integrações selecionada, mostrando a lista de integrações existentes. - 2
Inicie uma nova integração
Clique no botão Criar integração no canto superior direito. Você precisa da permissão de Criar integração — administradores da organização já a possuem por padrão.
O botão Criar integração em destaque no canto superior direito da aba Integrações. - 3
Opcional: use o preset de certificadora
No topo do diálogo, a caixa Configuração rápida oferece um preset de um clique. Clique em Usar preset de certificadora para configurar, em uma única etapa, uma certificadora que pode ler, baixar e revisar — sem descriptografia. Você ainda pode ajustar tudo depois, ou pular o preset e configurar as opções manualmente.
A caixa Configuração rápida com o botão Usar preset de certificadora no topo do diálogo. - 4
Dê um nome à integração
Dê à integração um nome que identifique a certificadora, como o nome da empresa auditora (por exemplo, "Certificadora ACME"). Esse rótulo ajuda os administradores a reconhecer a chave depois.
O diálogo de criação de integração com o campo Nome preenchido e o preset de Configuração rápida no topo. - 5
Defina a expiração do token de acesso
Em Expiração do token de acesso, escolha por quanto tempo o token permanece válido. Recomendamos 90 dias, para que um token vazado tenha vida útil limitada. Você também pode escolher uma data personalizada (até 180 dias) ou, apenas quando estritamente necessário, definir que ele nunca expira.
As opções de Expiração do token de acesso no diálogo de criação de integração. - 6
Escolha as permissões
Em Permissões, escolha o que a integração pode fazer: Ler arquivos lista os arquivos e lê seus detalhes, Baixar arquivos baixa o conteúdo dos arquivos, Revisar evidências permite participar das revisões de certificação, e Descriptografar arquivos permite abrir os arquivos criptografados da sua organização. Recomendamos manter Ler arquivos, Baixar arquivos e Revisar evidências ativados e deixar Descriptografar arquivos desativado, a menos que a certificadora realmente precise ler arquivos descriptografados.
A seção Permissões com Ler arquivos, Baixar arquivos e Revisar evidências ativados e Descriptografar arquivos desativado. - 7
Defina a expiração do acesso de descriptografia (opcional)
Necessário apenas quando você ativa Descriptografar arquivos. Desbloqueie primeiro suas chaves de criptografia para que a plataforma possa encapsular a chave da sua organização para a integração. Em seguida, defina a Expiração do acesso de descriptografia — recomendamos 365 dias, até no máximo 730 dias.
As opções de Expiração do acesso de descriptografia exibidas após ativar Descriptografar arquivos. - 8
Crie e copie as credenciais
Clique em Criar e confirme o código de 6 dígitos na janela Verifique sua identidade. A plataforma então exibe o token Bearer — e, se você concedeu files:decrypt, a chave privada da integração. Essas credenciais são exibidas apenas uma vez e não podem ser recuperadas, então copie-as e guarde-as imediatamente em um cofre seguro.
O diálogo de credenciais mostrando o token Bearer com o aviso de exibição única. - 9
Entregue as credenciais à certificadora com segurança
Compartilhe o token com a certificadora por um canal seguro (nunca por e-mail comum). A certificadora autentica cada requisição enviando-o no cabeçalho Authorization: Bearer, como mostrado na seção Usando o token.
A nova integração agora aparecendo como ativa na lista de integrações.
As credenciais são exibidas apenas uma vez
O token Bearer e a chave privada nunca são armazenados de forma recuperável. Se você perdê-los, será preciso excluir a integração e criar uma nova.
Entendendo os escopos de acesso
Os escopos definem o que a certificadora pode fazer com o token. Conceda apenas o que a auditoria exigir.
files:read
Listar arquivos e ler seus metadados.
files:download
Gerar URLs pré-assinadas para baixar arquivos.
files:decrypt
Descriptografar arquivos. Isso gera um par de chaves dedicado para a integração e encapsula a chave da sua organização para que a certificadora possa ler o conteúdo criptografado.
review
Leia e publique mensagens de bate-papo de certificação, inicie revisões, aprove e solicite alterações nas evidências.
Usando o token
A certificadora autentica cada requisição enviando o token no cabeçalho Authorization:
Authorization: Bearer <your-token>Boas práticas de segurança
Prefira validades curtas
Um token que expira limita o dano caso vaze. Evite tokens que nunca expiram, a menos que a certificadora realmente precise de acesso ininterrupto.
Conceda o mínimo privilégio
Habilite apenas os escopos que a certificadora precisa para a auditoria atual. Você pode criar uma nova integração mais restrita em vez de conceder permissões excessivas a uma existente.
Rotacione periodicamente
Rotacione o token na lista de integrações para emitir um novo segredo e invalidar o antigo — útil ao final de cada ciclo de auditoria.
Revogue ao terminar
Quando a auditoria terminar ou uma chave puder estar comprometida, desative a integração imediatamente. O acesso é interrompido no momento em que ela é revogada.
Perguntas frequentes
Administradores da organização e qualquer membro com a permissão de Criar integração. Se você não vê o botão Criar integração, peça a um administrador que conceda a permissão ou crie a chave para você.
Emitir uma chave de API é uma ação sensível, então a plataforma exige 2FA na sua conta e pede a confirmação de um código sempre que você cria ou rotaciona uma chave. Se você ainda não tem 2FA, ative-o em Perfil → Segurança (veja a seção Autenticação de dois fatores acima). Sem ele, a ação Criar integração fica bloqueada.
Não. O token Bearer e a chave privada são exibidos apenas uma vez, no momento da criação, e nunca são armazenados de forma recuperável. Se você perdê-los, exclua a integração e crie uma nova.
Apenas se ela precisar ler o conteúdo descriptografado dos seus arquivos. Se ler os metadados e baixar os arquivos (ainda criptografados) for suficiente, conceda apenas files:read e files:download. O escopo files:decrypt gera um par de chaves dedicado e exige que você desbloqueie suas chaves de criptografia durante a criação.
Requisições feitas com um token expirado são rejeitadas. Para restaurar o acesso, rotacione o token na lista de integrações ou crie uma nova integração. Escolher uma validade mais curta limita o impacto caso um token vaze.
Abra a aba Integrações, localize a integração e desative-a. O acesso é cortado imediatamente. Faça isso assim que uma auditoria terminar ou se você suspeitar que uma credencial foi exposta.
Use um canal seguro, como um gerenciador de senhas compartilhado ou um cofre de segredos — nunca e-mail ou chat comum. A certificadora então envia o token no cabeçalho Authorization: Bearer em cada requisição.
Precisa de mais informações?
Se você tiver dúvidas sobre a emissão de chaves de API, escopos ou como conectar uma certificadora à sua organização, entre em contato conosco.
Suporte por e-mail
Entre em contato com seu administrador ou nossa equipe de suporte
Documentação
Verifique nossa documentação técnica para mais detalhes