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
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 está ativada na sua conta. Ela é obrigatória para criar uma chave de API, e o guia de 2FA mostra como configurar.
- 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.
- Um canal seguro para entregar as credenciais, como um gerenciador de senhas ou cofre de segredos.
- Clareza sobre quais escopos a certificadora precisa, para conceder o mínimo privilégio.
O 2FA é obrigatório para criar uma chave
Sem o 2FA ativado, a ação Criar integração fica bloqueada. Ative uma vez na sua conta e você já pode emitir chaves. A partir daí, sempre que criar ou rotacionar uma chave, aparece a janela Verifique sua identidade pedindo o código de 6 dígitos.
Gerando a chave de API
Acesse as configurações da sua organização
Na plataforma, abra as configurações da organização e vá até a aba Integrações. É onde ficam listadas todas as chaves de API emitidas.
Inicie uma nova integração
Clique em Criar integração no canto superior direito. Você precisa da permissão de Criar integração; administradores já a possuem por padrão.
Opcional: use o preset de certificadora
No topo do diálogo, a caixa Configuração rápida oferece um preset de um clique, que configura uma certificadora capaz de ler, baixar e revisar, sem descriptografia. Você pode ajustar tudo depois, ou pular o preset e configurar manualmente.
Dê um nome à integração
Use um nome que identifique quem recebe o acesso, porque é assim que ela aparece na lista depois.
Defina a 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. Também é possível uma data personalizada de até 180 dias ou, só quando estritamente necessário, que ele nunca expire.
Escolha as permissões
Recomendamos manter Ler arquivos, Baixar arquivos e Revisar evidências ativados, e deixar Descriptografar arquivos desativado, a menos que a certificadora realmente precise ler o conteúdo descriptografado.
Defina a expiração do acesso de descriptografia
Necessário apenas se você ativou Descriptografar arquivos. Desbloqueie primeiro suas chaves de criptografia, para que a plataforma possa encapsular a chave da organização para a integração. Recomendamos 365 dias, até no máximo 730.
Crie e copie as credenciais
Clique em Criar e confirme o código de 6 dígitos. A plataforma exibe o token Bearer e, se você concedeu descriptografia, a chave privada da integração.
Entregue as credenciais com segurança
Compartilhe o token por um canal seguro, nunca por e-mail comum. A certificadora
autentica cada requisição enviando-o no cabeçalho Authorization: Bearer.
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, é 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.
| Escopo | O que permite |
|---|---|
files:read | Listar arquivos e ler seus metadados. |
files:download | Gerar URLs pré-assinadas para baixar arquivos. |
files:decrypt | Descriptografar arquivos. Gera um par de chaves dedicado e encapsula a chave da organização. |
review | Ler e publicar mensagens de certificação, iniciar revisões, aprovar e solicitar alterações. |
Usando o token
A certificadora autentica cada requisição enviando o token no cabeçalho
Authorization:
Authorization: Bearer <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 precise de acesso ininterrupto.
Conceda o mínimo privilégio
Habilite só os escopos necessários para a auditoria atual. Prefira criar uma integração mais restrita a ampliar uma existente.
Rotacione periodicamente
Rotacionar emite um novo segredo e invalida o antigo, o que é útil ao fim de cada ciclo de auditoria.
Revogue ao terminar
Quando a auditoria acabar, ou se uma chave puder estar comprometida, desative a integração. O acesso para no mesmo instante.
Perguntas frequentes
Quem pode criar uma chave de API?
Administradores da organização e qualquer membro com a permissão de Criar integração. Se você não vê o botão, peça a um administrador que conceda a permissão ou crie a chave para você.
Por que preciso de autenticação de dois fatores para criar uma chave?
Emitir uma chave de API é uma ação sensível, então a plataforma exige 2FA e pede confirmação de um código sempre que você cria ou rotaciona uma chave. Sem ele, a ação fica bloqueada.
Perdi o token. Posso vê-lo novamente?
Não. O token Bearer e a chave privada são exibidos apenas uma vez, na criação, e nunca são armazenados de forma recuperável. Se perder, exclua a integração e crie outra.
A certificadora precisa do escopo de descriptografia?
Apenas se precisar ler o conteúdo descriptografado. Se ler metadados e baixar os arquivos ainda criptografados for suficiente, conceda só leitura e download. O escopo de descriptografia gera um par de chaves dedicado e exige que você desbloqueie suas chaves durante a criação.
O que acontece quando o token expira?
Requisições com token expirado são recusadas. Para restaurar o acesso, rotacione o token na lista de integrações ou crie uma nova. Validade mais curta limita o impacto de um vazamento.
Como eu revogo o acesso?
Abra a aba Integrações, localize a integração e desative-a. O acesso é cortado imediatamente. Faça isso assim que a auditoria terminar ou se suspeitar que uma credencial foi exposta.
Como devo enviar as credenciais à certificadora?
Use um canal seguro, como gerenciador de senhas compartilhado ou cofre de segredos, nunca e-mail ou chat comum.