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

# Autorização do Agente

> Autorização baseada em escopo, gerenciamento de sessão e invocação de ferramentas para agentes de IA.

# Autorização do Agente

Todo agente de IA na plataforma Truthlocks opera sob um modelo de autorização rigoroso. Os agentes devem ser registrados, ter escopos atribuídos e criar sessões com tempo limitado antes de poderem realizar qualquer ação.

## Fluxo de Autorização

```
Register Agent → Assign Scopes → Create Session → Execute Actions → Terminate Session
      │               │                │                │               │
      ▼               ▼                ▼                ▼               ▼
  agent_id        scope_ids       session_token    audit_logged      cleanup
```

> [!TIP]
>
> Todos os endpoints de autorização de agente — escopos, sessões e ferramentas — possuem um playground de API interativo. Abra qualquer endpoint na referência da API [Sessões e Ferramentas do Agente](https://docs.truthlocks.com/pt/api-reference/machine-identity/sessions/create.md) e clique em **Enviar** para testá-lo no Sandbox.

## Modelo de escopo

Os escopos seguem um padrão hierárquico `resource:action`. Quando um agente solicita uma sessão, ele só pode solicitar escopos que foram atribuídos no registro.

### Definindo Escopos Personalizados

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/scopes \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "name": "invoices:approve",
    "description": "Approve invoices up to configured threshold",
    "constraints": {
      "max_amount_cents": 500000,
      "require_dual_approval_above": 100000
    }
  }'
```

### Escopos Integrados

| Escopo | Descrição |
| - | - |
| `agents:read` | Listar e inspecionar agentes |
| `agents:write` | Registrar e atualizar agentes |
| `receipts:write` | Recibos de ação de cunhagem |
| `attestations:read` | Ler dados de atestado |
| `attestations:write` | Criar novos atestados |
| `trust-scores:read` | Ler dados de pontuação de confiança |
| `trust-scores:compute` | Acionar recálculo da pontuação de confiança |
| `delegations:offer` | Oferecer delegação entre inquilinos |
| `delegations:accept` | Aceitar ofertas de delegação |
| `compliance:write` | Criar verificações de conformidade |
| `orchestrations:execute` | Executar fluxos de trabalho multi-agente |
| `datasets:attest` | Atestar a proveniência do conjunto de dados |
| `models:attest` | Atestar a linhagem do modelo |

## Gerenciamento de Sessão

As sessões fornecem contextos de execução com tempo limitado com expiração automática e lista de permissões de IP opcional.

### Criando uma Sessão

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/agent-sessions \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "scopes": ["receipts:write", "attestations:read"],
    "ttl_seconds": 3600,
    "ip_allowlist": ["10.0.0.0/8"],
    "metadata": {
      "task": "process-quarterly-invoices",
      "initiated_by": "user:alice@corp.com"
    }
  }'
```

**Resposta:**

```json theme={null}
{
  "id": "maip-session:01JYYYY",
  "agent_id": "maip-agent:01JXXXX",
  "token": "mst_live_...",
  "scopes": ["receipts:write", "attestations:read"],
  "expires_at": "2026-04-06T13:00:00Z",
  "status": "active"
}
```

### Ciclo de Vida da Sessão

| Status | Descrição |
| - | - |
| `active` | A sessão é válida e aceita requisições |
| `expired` | TTL expirado — limpeza automática |
| `terminated` | Terminado explicitamente pelo utilizador ou sistema |
| `suspended` | Pausado devido à detecção de anomalias |

### Encerrando uma Sessão

```bash theme={null}
curl -X DELETE https://api.truthlocks.com/v1/agent-sessions/maip-session:01JYYYY \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Task completed" }'
```

## Registro e Invocação de Ferramentas

Os agentes podem registrar ferramentas que expõem e invocar ferramentas registradas por outros agentes (sujeito a verificações de escopo).

### Registrar uma Ferramenta

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/tools \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "name": "generate-invoice",
    "description": "Generate PDF invoice from order data",
    "input_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "format": { "type": "string", "enum": ["pdf", "html"] }
      },
      "required": ["order_id"]
    }
  }'
```

### Invocar uma ferramenta

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/tools/invoice-generator/invoke \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "session_id": "maip-session:01JYYYY",
    "input": { "order_id": "ord_123", "format": "pdf" }
  }'
```

Toda invocação de ferramenta é:

1. **Escopo verificado** — a sessão deve ter o escopo necessário
2. **Com limite de taxa** — de acordo com a cota de invocação de ferramentas do seu plano
3. **Registrado em auditoria** — entrada/saída completa registrada no rastro de auditoria
4. **Medido** — contado em relação aos seus direitos de faturamento

## Melhores práticas de segurança

> [!WARNING]
>
> Nunca incorpore tokens de sessão em código do lado do cliente. Os tokens de sessão concedem o escopo total da sessão e devem ser tratados como segredos.

1. **Princípio do menor privilégio** — Solicite apenas os escopos necessários para a tarefa atual
2. **Sessões de curta duração** — Use o TTL mais curto possível (padrão: 1 hora)
3. **Lista de permissões de IP** — Restringir sessões a intervalos de rede conhecidos
4. **Rotacionar credenciais** — Regenerar chaves de assinatura do agente em um cronograma regular
5. **Monitorar pontuações de confiança** — Defina alertas quando as pontuações de confiança caírem abaixo dos limites
6. **Use o kill switch** — Revogue imediatamente agentes comprometidos

## Próximos passos

> [card] [Políticas MAIP](https://docs.truthlocks.com/guides/maip-policies.md)
>
> Regras de aplicação em tempo de execução baseadas em pontuações de confiança, escopos e profundidade de delegação.

> [card] [Pontuações de Confiança](https://docs.truthlocks.com/guides/trust-scores.md)
>
> Avaliação contínua de confiança comportamental para agentes.

> [card] [Delegação entre Inquilinos](https://docs.truthlocks.com/guides/cross-tenant-delegation.md)
>
> Permitir que agentes atuem além das fronteiras organizacionais.


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