Saltar para o conteúdo principal
Truthlocks suporta vários métodos de autenticação para proteger o acesso à API. Este guia abrange chaves de API, tokens JWT e melhores práticas de segurança.

Métodos de Autenticação

Chaves de API

Credenciais de longa duração para comunicação servidor-servidor. Recomendado para serviços de backend.

Tokens de Portador (JWT)

Tokens de curta duração para usuários autenticados. Ideal para aplicações frontend e contexto do usuário.

Chaves de API

Truthlocks possui dois tipos de chaves de API, dependendo de como você usa a plataforma:

Passando sua chave

Inclua sua chave de API usando um destes cabeçalhos:
Você também pode usar o cabeçalho Authorization com o esquema ApiKey:
Esses formatos autenticam endpoints habilitados para chave de API. Algumas operações exigem um token de portador de usuário e verificações de função; endpoints de saúde pública não precisam de nenhum. X-API-Key é mais comum nos exemplos ao longo desta documentação.

Chaves de API do inquilino

As chaves de locatário são o principal método de autenticação para organizações que usam Truthlocks. Elas são restritas a um locatário e suportam permissões granulares.

Estrutura chave

Escopos

As chaves de API do locatário podem ser restritas a permissões específicas:
Princípio do menor privilégio: Conceda apenas os escopos que sua aplicação realmente precisa. Uma chave com apenas attestations:mint não deve ter também users:write.

Criando uma chave de locatário

Via console

  1. Navegue para console.truthlocks.com/api-keys
  2. Clique em “Criar Chave de API”
  3. Digite um nome descritivo (por exemplo, “Backend de Produção”)
  4. Selecione o ambiente (produção ou sandbox) e os escopos necessários
  5. Copie a chave imediatamente — ela não será mostrada novamente

Via API

Request
Response
Crítico: O campo secret é retornado apenas uma vez no momento da criação. Armazene-o imediatamente em um gerenciador de segredos.

Chaves de API do consumidor

As chaves de consumidor permitem que usuários individuais acessem as APIs de proteção e verificação programaticamente — por exemplo, para cunhar atestações de um pipeline de CI ou integrar proteção de conteúdo em suas próprias ferramentas.

Detalhes chave

  • Cada conta suporta até 5 chaves ativas.
  • As chaves expiram automaticamente após 90 dias.
  • Chaves revogadas ou expiradas não podem ser reativadas — crie uma nova em vez disso.

Escopos fixos

As chaves de consumidor são emitidas com um conjunto fixo de escopos que não podem ser personalizados:

Criando uma chave de consumidor

1

Abrir configurações

Na barra lateral do portal de verificação, vá para Configurações > Chaves de API.
2

Criar uma chave

Clique em Criar Chave de API, insira um nome descritivo e confirme. O completo o segredo é exibido uma vez — copie e armazene-o com segurança.
3

Usar a chave

Passe a chave no cabeçalho X-API-Key com cada solicitação:
Para detalhes completos sobre a gestão de chaves de consumidor, consulte o guia do portal do consumidor.

Tokens de Portador (JWT)

Os tokens JWT são usados quando você precisa fazer chamadas de API em nome de um usuário autenticado, como de um aplicativo web ou móvel.

Usando Tokens de Portador

Estrutura do Token

Tempo de Vida do Token

Autenticador MFA para contas do Console

No Console, abra Configurações → Segurança → MFA do Autenticador para conectar o Google Authenticator ou outro aplicativo autenticador baseado em tempo.
  1. Confirme sua senha local atual do Truthlocks.
  2. Escaneie o código QR privado ou insira a chave de configuração em seu autenticador como uma conta baseada em tempo.
  3. Digite o código de seis dígitos do aplicativo para habilitar a MFA.
  4. Salve os dez códigos de recuperação mostrados após a confirmação. Eles são exibidos uma vez, e cada código funciona uma vez.
Novos inícios de sessão exigem o segundo fator após a sua palavra-passe ou o seu fornecedor de identidade empresarial. A etapa de verificação expira após cinco minutos. Códigos incorretos repetidos bloqueiam temporariamente a verificação da conta. Um código que já foi aceite não pode ser reutilizado. Para substituir códigos de recuperação ou desativar MFA, confirme sua senha e um novo código de autenticador ou código de recuperação não utilizado. A substituição de códigos de recuperação invalida o conjunto anterior. Usuários de SSO que nunca definiram uma senha local do Truthlocks podem usar o fluxo de redefinição de senha para seu e-mail registrado antes da inscrição. A inscrição de MFA se aplica à sua própria conta. Não inscreve outros membros nem impõe um requisito de MFA em todo o espaço de trabalho. A ativação da MFA não revoga automaticamente as sessões existentes. As chaves de API permanecem credenciais de sistema separadas.

Melhores práticas de segurança

✅ Usar Gerenciamento de Segredos

Armazene chaves de API no Google Secret Manager, HashiCorp Vault ou similar. Nunca chaves codificadas no código do aplicativo.

✅ Rotacionar Chaves Regularmente

Crie novas chaves e revogue as antigas periodicamente. Use nomes descritivos com datas (por exemplo, “Backend-2026-Q1”).

✅ Restringir Escopos

Conceda apenas as permissões realmente necessárias. Revise e audite os escopos das chaves regularmente.

❌ Nunca Expor no Frontend

As chaves de API nunca devem ser incluídas no JavaScript do lado do cliente. Use tokens JWT para autenticação de frontend.

❌ Nunca Cometer para o Git

Use variáveis de ambiente ou gerenciamento de segredos. Adicione .env* a .gitignore.

Próximos passos

Portal do consumidor

Gerencie chaves de API do consumidor, proteções e configurações.

Ambientes

Configuração de sandbox vs. produção e URLs base.

RBAC e permissões

Entenda funções, permissões e controle de acesso.

Registros de auditoria

Rastreie todas as atividades da API e eventos de segurança.