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

# Políticas de emissão

> Defina políticas baseadas em regras que controlam quem pode cunhar, verificar e exportar atestações em seu inquilino.

As políticas de emissão permitem que você aplique requisitos de conformidade, jurisdição e confiança em toda a cunhagem, verificação e exportação de pacotes de prova. Quando uma política está ativa, cada solicitação correspondente é avaliada em relação às suas regras antes de prosseguir. As solicitações que não correspondem são negadas com um motivo claro.

## Quando usar políticas

Use políticas de emissão quando precisar:

* Restringir a cunhagem a emissores em jurisdições específicas (por exemplo, apenas EUA ou EUA e UE)
* Exigir um nível mínimo de confiança antes que um emissor possa criar atestações
* Impor regras diferentes para cunhagem vs. verificação
* Controlar quem pode exportar pacotes de prova ou enviar solicitações de portabilidade de dados
* Testar uma política com entradas de amostra antes de implantar em produção
* Auditar qual política estava em vigor quando uma atestação foi criada

Se você não criar nenhuma política, todas as solicitações de cunhagem, verificação e exportação serão permitidas por padrão.

## Como as políticas funcionam

Cada política contém uma ou mais **regras**. Uma regra tem:

* **Condições** — verificações em nível de campo avaliadas em relação ao contexto da solicitação (por exemplo, `jurisdiction eq US`)
* **Efeito** — `ALLOW` ou `DENY` se as condições corresponderem
* **Efeito padrão** — aplicado quando nenhuma regra corresponde

As regras são avaliadas em ordem. A primeira regra correspondente determina o resultado. Se nenhuma regra corresponder, o `default_effect` se aplica.

```json theme={null}
{
  "rules": [
    {
      "id": "us_only",
      "description": "US jurisdiction required",
      "conditions": [
        { "field": "jurisdiction", "op": "eq", "value": "US" }
      ],
      "effect": "ALLOW"
    }
  ],
  "default_effect": "DENY"
}
```

### Operadores de condição

| Operador | Descrição | Exemplo |
| - | - | - |
| `eq` | Igual a | `{ "field": "jurisdiction", "op": "eq", "value": "US" }` |
| `neq` | Diferente de | `{ "field": "trust_tier", "op": "neq", "value": "individual" }` |
| `in` | Corresponde a qualquer valor em uma lista | `{ "field": "trust_tier", "op": "in", "value": ["verified_org", "enterprise"] }` |
| `nin` | Não corresponde a nenhum valor numa lista | `{ "field": "jurisdiction", "op": "nin", "value": ["CN", "RU"] }` |
| `gt` | Maior que (numérico) | `{ "field": "key.age_days", "op": "gt", "value": 90 }` |
| `lt` | Menor que (numérico) | `{ "field": "key.age_days", "op": "lt", "value": 365 }` |
| `exists` | O campo está presente | `{ "field": "jurisdiction", "op": "exists", "value": true }` |

As condições suportam notação de ponto para campos aninhados (por exemplo, `key.age_days`, `key.status`).

### Campos disponíveis

Qualquer campo na entrada de avaliação pode ser referenciado, incluindo campos aninhados com notação de ponto. Os seguintes campos estão disponíveis por padrão:

| Campo | Descrição |
| - | - |
| `jurisdiction` | A jurisdição registrada do emissor (código de país ISO) |
| `trust_tier` | O nível de confiança do emissor (`individual`, `verified_org`, `regulated_issuer`, `enterprise`) |
| `status` | O status atual do emissor (`ACTIVE`, `suspended`, `revoked`, `SUNSET`, `pending`) |
| `risk_rating` | A classificação de risco do emissor (`low`, `medium`, `high`, `CRITICAL`) |
| `assurance_level` | O nível de garantia do emissor (`standard`, `high`, `regulated`) |
| `key.age_days` | Idade da chave de assinatura em dias |
| `key.status` | Status da chave de assinatura (`ACTIVE`, `REVOKED`, `EXPIRED`) |
| `key.kid` | Identificador da chave de assinatura |

## Ciclo de vida da política

Cada política tem um status que controla se ela é aplicada:

| Status | Comportamento |
| - | - |
| `DRAFT` | Salvo, mas não aplicado — use isso enquanto você itera nas regras |
| `ACTIVE` | Aplicado em cada pedido correspondente |
| `DISABLED` | Desativado temporariamente sem excluir a política |

Ao criar uma política, você escolhe o status inicial. Apenas políticas `ACTIVE` são avaliadas no momento da requisição.

### Transições de ciclo de vida

As políticas geralmente seguem esta progressão:

1. **Criar como `DRAFT`** — escreva e refine suas regras sem afetar o tráfego ao vivo.
2. **Simular** — teste a política de rascunho com entradas de amostra usando o [simulador de política](#simulating-a-policy).
3. **Ativar** — defina o status como `ACTIVE` para que a política seja aplicada às solicitações correspondentes.
4. **Desativar** — defina o status como `DISABLED` para interromper temporariamente a aplicação sem perder a definição da política.
5. **Excluir** — remover a política inteiramente quando não for mais necessária.

Você pode fazer a transição entre `DRAFT`, `ACTIVE` e `DISABLED` a qualquer momento, atualizando a política. Cada mudança de status incrementa a versão da política, que é registrada junto com cada decisão de avaliação para fins de auditoria.

> [!NOTE]
>
> A transição de uma política para `ACTIVE` entra em vigor imediatamente. Certifique-se de ter testado as regras com o simulador antes de ativar.

## Categorias de políticas

As políticas são restritas a uma ação específica:

| Categoria | Aplica-se a |
| - | - |
| `MINT` | Solicitações de cunhagem de atestado |
| `VERIFY` | Solicitações de verificação |
| `BUNDLE_EXPORT` | Exportação de pacote de prova e solicitações de portabilidade de dados |

Você pode ter várias políticas ativas. Cada política se aplica apenas à sua categoria.

### Políticas de controlo de exportação

As políticas `BUNDLE_EXPORT` controlam quem pode exportar pacotes de prova e enviar solicitações de portabilidade de dados. Use-as para restringir exportações por jurisdição, nível de confiança ou qualquer outro campo na entrada de avaliação.

```json theme={null}
{
  "rules": [
    {
      "id": "block_non_enterprise",
      "description": "Only enterprise-tier issuers can export bundles",
      "conditions": [
        { "field": "trust_tier", "op": "nin", "value": ["enterprise", "regulated_issuer"] }
      ],
      "effect": "DENY"
    },
    {
      "id": "allow_low_risk",
      "description": "Allow exports for low-risk issuers",
      "conditions": [
        { "field": "risk_rating", "op": "eq", "value": "low" }
      ],
      "effect": "ALLOW"
    }
  ],
  "default_effect": "DENY"
}
```

Para criar esta política via API, defina `category` como `BUNDLE_EXPORT`:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/policies \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Export Only",
    "category": "BUNDLE_EXPORT",
    "status": "ACTIVE",
    "description": "Restrict proof-bundle exports to enterprise issuers with low risk",
    "language": "json_rules",
    "rules": {
      "rules": [
        {
          "id": "block_non_enterprise",
          "description": "Only enterprise-tier issuers can export bundles",
          "conditions": [
            { "field": "trust_tier", "op": "nin", "value": ["enterprise", "regulated_issuer"] }
          ],
          "effect": "DENY"
        }
      ],
      "default_effect": "ALLOW"
    }
  }'
```

### Vinculações de política

As vinculações de política conectam uma política a um destino específico para que o mecanismo saiba quando aplicá-la. Cada vinculação inclui:

| Campo | Tipo | Descrição |
| - | - | - |
| `policy_id` | string | O ID da política a ser vinculada |
| `target_type` | string | `ISSUER`, `VERIFICATION_PROFILE`, ou `TENANT_DEFAULT` |
| `target_id` | string | UUID do alvo. Omita para `TENANT_DEFAULT` para aplicar a política a todas as entidades. |
| `action` | string | `MINT`, `VERIFY`, ou `BUNDLE_EXPORT` |
| `priority` | integer | As vinculações de maior prioridade são avaliadas primeiro |

Quando múltiplas vinculações correspondem a uma requisição, elas são avaliadas em ordem decrescente de prioridade. O primeiro resultado `DENY` interrompe a avaliação imediatamente.

#### Criando uma vinculação via API

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/policies/bindings \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "pol_abc123",
    "target_type": "ISSUER",
    "target_id": "iss_def456",
    "action": "MINT",
    "priority": 100
  }'
```

Para aplicar uma política como padrão em todo o locatário, defina `target_type` como `TENANT_DEFAULT` e omita `target_id`:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/policies/bindings \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "pol_abc123",
    "target_type": "TENANT_DEFAULT",
    "action": "MINT",
    "priority": 10
  }'
```

> [!TIP]
>
> Use valores de prioridade mais altos para vinculações mais específicas. Por exemplo, atribua prioridade `100` a uma vinculação de nível de emissor e `10` ao padrão do locatário para que a política específica do emissor seja avaliada primeiro.

## Criar uma política

### A partir da consola

1. Vá para **Políticas** na barra lateral do console
2. Clique em **Criar política**
3. Digite um nome, selecione uma categoria (`MINT`, `VERIFY` ou `BUNDLE_EXPORT`) e escolha um status
4. Escreva suas regras em formato JSON ou use um modelo
5. Clique em **Implantar Política** — se o status for `ACTIVE`, ela entra em vigor imediatamente

### A partir de um modelo

O console inclui quatro modelos prontos para uso que você pode adicionar com um clique:

| Modelo | Categoria | Descrição |
| - | - | - |
| Permitir Jurisdição dos EUA | MINT | Permitir apenas cunhagem de emissores baseados nos EUA |
| Somente Organização Verificada | MINT | Exigir nível de confiança `verified_org` ou superior |
| Permitir Tudo (Permissivo) | MINT | Permitir todas as cunhagens — use com cautela |
| Verificar - Somente EUA e UE | VERIFICAR | Aceitar apenas verificações de jurisdições dos EUA ou da UE |

Para usar um modelo, abra a aba **Modelos** na página de políticas e clique em **Usar modelo**. A política é criada e ativada imediatamente. Você pode editá-la posteriormente para personalizar as regras.

### Via API

Defina `status` como `DRAFT` se quiser salvar a política sem aplicá-la ainda.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/policies \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Issuers Only",
    "category": "MINT",
    "status": "ACTIVE",
    "description": "Restrict minting to US-based issuers",
    "language": "json_rules",
    "rules": {
      "rules": [
        {
          "id": "us_only",
          "description": "US jurisdiction required",
          "conditions": [
            { "field": "jurisdiction", "op": "eq", "value": "US" }
          ],
          "effect": "ALLOW"
        }
      ],
      "default_effect": "DENY"
    }
  }'
```

```json Response theme={null}
{
  "id": "pol_abc123",
  "name": "US Issuers Only",
  "category": "MINT",
  "status": "ACTIVE",
  "description": "Restrict minting to US-based issuers",
  "rules": { "..." },
  "version": 1,
  "created_at": "2026-03-31T10:00:00Z"
}
```

## Listando políticas

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

Retorna um array de todas as políticas para o locatário atual.

## Simulando uma política

Antes de confiar em uma política em produção, use o simulador para testar como ela avalia uma determinada entrada. No console, abra a guia **Simulador** na página de políticas, selecione uma política e insira uma entrada de teste.

Você também pode chamar o endpoint de avaliação diretamente:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/policies/evaluate \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "MINT",
    "target_type": "ISSUER",
    "input": {
      "jurisdiction": "US",
      "trust_tier": "ENTERPRISE"
    }
  }'
```

```json Response theme={null}
{
  "allowed": true,
  "matched_rules": ["us_only"],
  "reasons": [],
  "decision_id": "dec_7f3a1b"
}
```

A resposta inclui quatro campos:

| Campo | Tipo | Descrição |
| - | - | - |
| `allowed` | boolean | Se a solicitação passou por todas as políticas ativas |
| `matched_rules` | string\[] | IDs das regras que corresponderam à entrada. Vazio quando nenhuma regra correspondeu e o efeito padrão foi aplicado. |
| `reasons` | string\[] | Explicação legível por humanos quando uma solicitação é negada. Sempre um array vazio quando `allowed` é `true`. |
| `decision_id` | string | Identificador único para esta avaliação — use-o para consultar o registro de decisão completo na [trilha de auditoria](https://docs.truthlocks.com/pt/security/audit.md#policy-decision-audit-trail). |

> [!NOTE]
>
> Se você anteriormente dependia de `evaluation_ms` na resposta de avaliação para monitoramento de desempenho, esse campo foi removido da resposta da API. Ele ainda é registrado no [rastro de auditoria de decisão](#decision-audit-trail) — consulte `resource_type=policy_decision` no [log de auditoria](https://docs.truthlocks.com/pt/security/audit.md#policy-decision-audit-trail) para recuperá-lo.

Se nenhuma regra corresponder, a resposta reflete o `default_effect`:

```json theme={null}
{
  "allowed": false,
  "matched_rules": [],
  "reasons": ["Default policy effect: DENY"],
  "decision_id": "dec_9c2d4e"
}
```

## Trilha de auditoria de decisão

Toda avaliação de política é registrada automaticamente. Cada decisão captura a versão da política, as regras correspondentes e um hash SHA-256 da entrada para evidência de adulteração. Use os registros de decisão para rastrear por que uma solicitação específica foi permitida ou negada.

A resposta de avaliação inclui um `decision_id` que você pode referenciar em consultas de auditoria:

```bash theme={null}
curl "https://api.truthlocks.com/v1/audit/events?resource_type=policy_decision&resource_id=dec_7f3a1b" \
  -H "X-API-Key: tl_live_..."
```

O registro de auditoria inclui campos que não fazem parte da resposta da API de avaliação, como `evaluation_ms` e `input_hash`:

| Campo de decisão | Descrição |
| - | - |
| `decision_id` | Identificador exclusivo para esta avaliação |
| `policy_id` | A política que foi avaliada |
| `policy_version` | Versão da política no momento da avaliação |
| `allowed` | Se a solicitação foi permitida |
| `matched_rules` | IDs de regras que corresponderam à entrada |
| `evaluation_ms` | Tempo gasto na avaliação, em milissegundos (somente trilha de auditoria) |
| `input_hash` | Hash SHA-256 da entrada de avaliação |

## Excluir uma política

Remova uma política da consola clicando no ícone de exclusão no cartão da política, ou através da API:

```bash theme={null}
curl -X DELETE https://api.truthlocks.com/v1/policies/{id} \
  -H "X-API-Key: tl_live_..."
```

> [!WARNING]
>
> A exclusão de uma política entra em vigor imediatamente. Quaisquer solicitações pendentes de cunhagem ou verificação que estavam sujeitas à política não serão mais avaliadas em relação a ela.

## Exemplo: política de múltiplas regras

Combine várias regras para expressar requisitos complexos. As regras são avaliadas em ordem — a primeira correspondência vence.

```json theme={null}
{
  "rules": [
    {
      "id": "block_individual",
      "description": "Block individual-tier issuers",
      "conditions": [
        { "field": "trust_tier", "op": "eq", "value": "individual" }
      ],
      "effect": "DENY"
    },
    {
      "id": "allow_us_eu",
      "description": "Allow US or EU jurisdictions",
      "conditions": [
        { "field": "jurisdiction", "op": "in", "value": ["US", "EU"] }
      ],
      "effect": "ALLOW"
    }
  ],
  "default_effect": "DENY"
}
```

Esta política nega emissores de nível individual, independentemente da jurisdição, permite emissores dos EUA e da UE em qualquer outro nível de confiança e nega todos os outros.

## Relacionado

> [card] [SDK do motor de políticas](https://docs.truthlocks.com/policy.md)
>
> Avalie políticas programaticamente usando o SDK para integração personalizada
> cenários.

> [card] [Referência da API de Políticas](https://docs.truthlocks.com/api-reference/policies/create.md)
>
> Crie, liste, avalie e exclua políticas via API REST.

> [card] [Exportações de conformidade](https://docs.truthlocks.com/guides/compliance-exports.md)
>
> Exporte dados de auditoria nos formatos SOC 2, GDPR e HIPAA para conformidade
> relatórios.

> [card] [Governança](https://docs.truthlocks.com/api-reference/governance/list-requests.md)
>
> Use fluxos de trabalho de governança para aprovação do emissor e alterações de status.


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