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

# Conceitos Essenciais

> Compreendendo inquilinos, emissores, atestados e verificação.

Este guia explica os blocos de construção fundamentais da plataforma Truthlocks. Compreender esses conceitos é essencial para uma integração eficaz.

## Inquilinos

Um **inquilino** é a unidade organizacional de nível superior na Truthlocks. Cada inquilino representa um cliente ou organização distinto com isolamento completo de dados.

| Propriedade | Descrição |
| - | - |
| `id` | UUID único que identifica o inquilino |
| `name` | Nome da organização legível por humanos |
| `slug` | Identificador seguro para URL (por exemplo, `acme-corp`) |
| `tier` | Nível de assinatura: FREE, STARTER, PROFESSIONAL, ENTERPRISE |
| `status` | ATIVO, SUSPENSO ou EXCLUÍDO |

### Controles de multi-tenancy

* **Isolamento de Dados:** Os dados de cada locatário são completamente isolados no nível do banco de dados
* **Limites de Recursos:** Limites de taxa e cotas são aplicados por inquilino
* **Escopo da Chave de API:** As chaves de API são vinculadas a um único locatário e não podem acessar dados de outros locatários
* **Separação de Auditoria:** Os logs de auditoria são particionados por locatário

## Emissores

Um **emissor** é uma entidade que pode criar e assinar atestados. Os emissores representam organizações, instituições ou serviços que fazem reivindicações sobre assuntos.

> [card] Identidade
>
> Cada emissor tem um domínio verificado (por exemplo, `acme.edu`) que estabelece sua
> identidade do mundo real.

> [card] Chaves Criptográficas
>
> Os emissores registram chaves públicas Ed25519 usadas para verificar assinaturas de atestação.

> [card] Status de Confiança
>
> Novos emissores são ativados imediatamente após a criação. Níveis de confiança mais altos exigem uma revisão da aplicação: ATIVO → SUSPENSO.

> [card] Nível de Confiança
>
> BÁSICO, VERIFICADO ou PREMIUM com base na profundidade da verificação de identidade.

### Ciclo de vida do emissor

```text theme={null}
                    ┌──────────────┐
                    │   CREATED    │
                    └───────┬──────┘
                            │ auto-activated
                            ▼
                    ┌──────────────┐
                    │    ACTIVE    │  ← Ready to mint (BASIC trust)
                    └───────┬──────┘
                            │
            suspend │               │ apply for higher tier
                    ▼               ▼
            ┌──────────────┐  ┌──────────────┐
            │   SUSPENDED  │  │   IN REVIEW  │
            └──────────────┘  └───────┬──────┘
                                      │
                              approve │ reject
                              ▼               ▼
                      ┌──────────────┐  ┌──────────────┐
                      │    ACTIVE    │  │   REJECTED   │
                      │ (higher tier)│  │ (keeps BASIC)│
                      └──────────────┘  └──────────────┘
```

> [!NOTE]
>
> Novos emissores são ativados imediatamente com o nível de confiança **Básico**. Nenhuma aprovação manual é necessária para começar a emitir atestados. Para atualizar para um nível de confiança superior (Organização Verificada, Entidade Governamental ou Instituição Acreditada), envie uma [solicitação de emissor](https://docs.truthlocks.com/pt/guides/issuer-applications.md) para revisão.

## Atestados

Um **atestado** é uma reivindicação criptograficamente assinada feita por um emissor sobre um assunto. Atestados são o primitivo central do sistema Truthlocks.

### Estrutura de Atestado

```json theme={null}
{
  "id": "uuid", // Unique identifier
  "issuer_id": "uuid", // Who signed it
  "kid": "string", // Key used to sign
  "status": "VALID", // Current status
  "payload": {
    "subject": "string", // Who/what the claim is about
    "claim": "string", // Type of claim (e.g., "verified_email")
    "value": "any", // The actual claim data
    "metadata": {} // Optional additional data
  },
  "signature": "base64", // Ed25519 signature
  "log_index": 42, // Position in transparency log
  "created_at": "datetime"
}
```

### Propriedades de Atestado

| Propriedade | Descrição |
| - | - |
| **Imutável** | Uma vez criados, o payload e a assinatura não podem ser modificados |
| **Revogável** | Os emissores podem revogar atestados, atualizando o status para REVOGADO |
| **Substituível** | Os emissores podem [substituir](https://docs.truthlocks.com/pt/api-reference/attestations/supersede.md) uma atestação por uma nova versão, criando uma cadeia auditável enquanto preservam a original |
| **Portátil** | O ID do atestado pode ser compartilhado e verificado em qualquer lugar |
| **Auditável** | Cada operação é registrada no log de transparência |

## Proteções ao consumidor

Uma **proteção ao consumidor** é um atestado criado através do fluxo simplificado de [cunhagem do consumidor](https://docs.truthlocks.com/pt/api-reference/consumer/mint.md), projetado para criadores individuais. Você faz o hash do seu arquivo no lado do cliente (SHA-256) e envia o hash junto com metadados como título, categoria e tipo de conteúdo. A Truthlocks provisiona sua identidade de assinatura automaticamente no primeiro uso.

A resposta de cunhagem do consumidor inclui:

| Campo | Descrição |
| - | - |
| `protection_id` | ID exclusivo para o registro de proteção |
| `attestation_id` | O ID de atestado subjacente (usado para verificação) |
| `content_hash` | O hash SHA-256 que você enviou, retornado para confirmação |
| `protected_at` | Carimbo de data/hora exato quando o conteúdo foi protegido |
| `verify_url` | URL da página de prova pública que você pode compartilhar com qualquer pessoa |
| `status` | Estado de confirmação (`protected`) |

Cada proteção gera uma página de prova pública. Qualquer pessoa pode buscar os metadados da página de prova via `GET /v1/public/proof/{attestation_id}` — nenhuma autenticação é necessária. Este endpoint é projetado para renderizar páginas de prova e gerar prévias de links do Open Graph para URLs compartilhadas. Consulte o [endpoint de metadados de prova](https://docs.truthlocks.com/pt/api-reference/consumer/proof-metadata.md) para detalhes.

## Sinais de risco

Um **sinal de risco** é uma observação pontuada de uma fonte de detecção de fraude — impressão digital do dispositivo, reputação de IP, verificação de e-mail, análise de documentos ou seu próprio motor de regras. Você pode ingerir sinais diretamente via API ou enviar eventos de identidade brutos e deixar a plataforma normalizá-los em sinais automaticamente.

Cada sinal inclui:

| Campo | Descrição |
| :- | :- |
| `signal_source` | De onde veio o sinal (por exemplo, `device_fingerprint`, `ip_reputation`, `login`) |
| `signal_type` | O que foi detectado (por exemplo, `velocity`, `geo_anomaly`, `ato`, `deepfake`) |
| `risk_score` | Pontuação de risco de `0` (seguro) a `100` (alto risco) — pontuações iguais ou superiores a 80 acionam revisão automática |
| `subject_id` | Identificador da entidade sendo avaliada |
| `subject_type` | O tipo de entidade: `user`, `issuer`, `session`, `device`, `ip`, ou `attestation` |
| `payload` | Metadados arbitrários (endereços IP, geolocalização, razões) |

### Normalização de eventos

Em vez de construir sinais de risco manualmente, você pode enviar eventos de identidade brutos — logins falhos, assinaturas inválidas, suspeitos de deepfake — para `POST /v1/risk/events`. A plataforma mapeia cada evento para um tipo de sinal canônico e pontuação de risco base automaticamente. Consulte a [referência da API de normalização de eventos de identidade](https://docs.truthlocks.com/pt/api-reference/risk/normalize-event.md).

Os sinais de risco são totalmente isolados por inquilino usando [segurança em nível de linha](https://docs.truthlocks.com/pt/security/rls.md) e formam a base do Firewall de Identidade Antifraude. Consulte o [guia de sinais de risco](https://docs.truthlocks.com/pt/guides/risk-signals.md) para detalhes de integração.

## Agentes de máquina

Um **agente de máquina** é um agente de IA, bot ou serviço automatizado registrado com o [Protocolo de Identidade de Agente de Máquina (MAIP)](https://docs.truthlocks.com/pt/guides/machine-identity.md). Cada agente recebe um identificador único (`maip-agent:<ulid>`) e um par de chaves Ed25519 para assinar recibos.

| Campo | Descrição |
| :- | :- |
| `agent_id` | Identificador MAIP exclusivo para o agente |
| `name` | Nome do agente legível por humanos (por exemplo, `order-processor`) |
| `type` | Tipo de agente: `autonomous`, `supervised`, `delegated`, ou `system` |
| `scopes` | Escopos de permissão que o agente está autorizado a usar |
| `status` | Status do ciclo de vida: `active`, `suspended`, ou `revoked` |
| `trust_score` | Pontuação de confiança comportamental contínua de 0 a 100 |

Os agentes operam dentro de **sessões** — contextos de execução de curta duração, com escopo limitado e expiração automática. Cada ação que um agente realiza gera um **recibo** criptograficamente assinado que se encadeia ao recibo anterior para trilhas de auditoria à prova de adulteração. Nove tipos de recibo cobrem todo o ciclo de vida do agente: gênese, delegação, ação, revogação, atestado de dados, atestado de modelo, conformidade, reivindicação de verdade e verificação.

Consulte o [guia de identidade da máquina](https://docs.truthlocks.com/pt/guides/machine-identity.md) para configuração e o [guia de autorização do agente](https://docs.truthlocks.com/pt/guides/agent-authorization.md) para o modelo de escopo e sessão.

## Pacotes de prova

Um **pacote de prova** é um pacote autocontido que inclui tudo o necessário para verificar um atestado offline, sem contatar os servidores da Truthlocks.

```json theme={null}
{
  "attestation": { ... },       // Full attestation object
  "issuer": {
    "id": "uuid",
    "name": "Acme University",
    "domain": "acme.edu",
    "trust_level": "VERIFIED"
  },
  "public_key": {
    "kid": "ed-key-2026",
    "algorithm": "Ed25519",
    "public_key_pem": "-----BEGIN PUBLIC KEY-----..."
  },
  "transparency_proof": {
    "log_index": 42,
    "root_hash": "sha256:...",
    "inclusion_proof": ["hash1", "hash2", ...]
  }
}
```

> [!NOTE]
>
> **Caso de Uso:** Pacotes de prova são ideais para cenários onde os verificadores podem estar
> offline ou deseja verificar independentemente sem chamadas de API.

## Modelo de Verificação

A verificação Truthlocks verifica várias camadas para determinar se um atestado deve ser confiável:

**1. Verificação Criptográfica**

Verifique se a assinatura Ed25519 corresponde à carga útil usando a chave pública do emissor.
chave.

**2. Verificação de Status**

Verifique se a atestação foi revogada ou substituída pelo emissor. Atestações substituídas se vinculam ao seu substituto via `superseded_by_attestation_id`.

**3. Status de Confiança do Emissor**

Confirme se o emissor está no status ATIVO e não suspenso.

**4. Validade da Chave**

Verifique se a chave de assinatura estava ativa no momento da criação do atestado.

## Próximos passos

> [card] [Ambientes](https://docs.truthlocks.com/environments.md)
>
> Saiba mais sobre ambientes de desenvolvimento vs. produção e configuração.

> [card] [Autenticação](https://docs.truthlocks.com/security/auth.md)
>
> Aprofunde-se em chaves de API, tokens JWT e integração OAuth.


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