> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Métodos de autenticação de API, gerenciamento de chaves e melhores práticas de segurança.

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

> [card] Chaves de API
>
> Credenciais de longa duração para comunicação servidor-servidor. Recomendado para
> serviços de backend.

> [card] 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:

| Tipo | Prefixo | Criado a partir de | Caso de uso |
| :- | :- | :- | :- |
| **Chave de inquilino** | `tl_live_` / `tl_test_` | [Console](https://console.truthlocks.com) | Integrações servidor-a-servidor, fluxos de trabalho empresariais |
| **Chave do consumidor** | `tlk_` | [Portal Verify ](https://verify.truthlocks.com) | Acesso pessoal à API para proteção e verificação de conteúdo |

### Passando sua chave

Inclua sua chave de API usando um destes cabeçalhos:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/issuers \
  -H "X-API-Key: tl_live_your_api_key"
```

Você também pode usar o cabeçalho `Authorization` com o esquema `ApiKey`:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/issuers \
  -H "Authorization: ApiKey tl_live_your_api_key"
```

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

```text theme={null}
tl_live_abc123def456gh789ijklmnopqrstuv
│  │    │
│  │    └── 32-character random identifier
│  └── Environment: test | live
└── Prefix: tl (Truthlocks)
```

### Escopos

As chaves de API do locatário podem ser restritas a permissões específicas:

| Escopo | Permissões |
| - | - |
| `attestations:mint` | Criar novas atestações |
| `attestations:read` | Ler detalhes da atestação e pacotes de prova |
| `attestations:revoke` | Revogar atestados |
| `issuers:read` | Visualizar informações do emissor |
| `issuers:write` | Criar e gerenciar emissores |
| `users:read` | Visualizar usuários e funções |
| `users:write` | Convidar usuários, gerenciar funções |
| `audit:read` | Consultar logs de auditoria |

> [!NOTE]
>
> **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](https://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

```bash Request theme={null}
curl -X POST https://api.truthlocks.com/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "scopes": ["attestations:mint", "attestations:read", "issuers:read"]
  }'
```

```json Response theme={null}
{
  "id": "key-uuid",
  "name": "Production Backend",
  "prefix": "tl_live_abc",
  "secret": "tl_live_abc123def456gh789ijklmnopqrstuv",
  "scopes": ["attestations:mint", "attestations:read", "issuers:read"],
  "created_at": "2026-01-13T12:00:00Z"
}
```

> [!WARNING]
>
> **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:

| Escopo | Permissões |
| :- | :- |
| `consumer:read` | Ler seu perfil de consumidor e configurações |
| `consumer:write` | Atualize seu perfil e configurações de consumidor |
| `attestations:mint` | Cunhar novas atestações |
| `attestations:read` | Ler seus atestados |
| `verify:read` | Verificar atestados |

### 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:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/consumer/protections \
  -H "X-API-Key: tlk_your_key_here"
```

Para detalhes completos sobre a gestão de chaves de consumidor, consulte o [guia do portal do consumidor](https://docs.truthlocks.com/pt/guides/consumer-portal.md#api-keys).

## 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

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
```

### Estrutura do Token

```json theme={null}
{
  "sub": "user-uuid",
  "tenant_id": "tenant-uuid",
  "email": "user@example.com",
  "roles": ["admin"],
  "iat": 1705147200,
  "exp": 1705150800,
  "iss": "https://auth.truthlocks.com"
}
```

### Tempo de Vida do Token

| Tipo de Token | Tempo de vida | Atualizar |
| - | - | - |
| Token de Acesso | 1 hora | Via token de atualização |
| Token de Atualização | 30 dias | Via reautenticação |

## 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

> [card] ✅ Usar Gerenciamento de Segredos
>
> Armazene chaves de API no Google Secret Manager, HashiCorp Vault ou similar. Nunca
> chaves codificadas no código do aplicativo.

> [card] ✅ Rotacionar Chaves Regularmente
>
> Crie novas chaves e revogue as antigas periodicamente. Use nomes descritivos com
> datas (por exemplo, "Backend-2026-Q1").

> [card] ✅ Restringir Escopos
>
> Conceda apenas as permissões realmente necessárias. Revise e audite os escopos das chaves
> regularmente.

> [card] ❌ 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.

> [card] ❌ Nunca Cometer para o Git
>
> Use variáveis de ambiente ou gerenciamento de segredos. Adicione `.env*` a
> `.gitignore`.

## Próximos passos

> [card] [Portal do consumidor](https://docs.truthlocks.com/guides/consumer-portal.md)
>
> Gerencie chaves de API do consumidor, proteções e configurações.

> [card] [Ambientes](https://docs.truthlocks.com/environments.md)
>
> Configuração de sandbox vs. produção e URLs base.

> [card] [RBAC e permissões](https://docs.truthlocks.com/security/rbac.md)
>
> Entenda funções, permissões e controle de acesso.

> [card] [Registros de auditoria](https://docs.truthlocks.com/security/audit.md)
>
> Rastreie todas as atividades da API e eventos de segurança.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.