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

# Autenticação

> Chaves de API, escopos, rotação, allowlist de IP, assinatura de requisição e idempotência

<Warning>
  Rascunho: especificação em definição. Endpoints e campos podem mudar.
</Warning>

## Chaves de API

Cada chave pertence a uma organização e é criada no painel por um usuário administrador. A chave completa aparece uma única vez, no momento da criação.

| Prefixo | Ambiente |
| - | - |
| `tesa_test_` | Sandbox |
| `tesa_live_` | Produção |

A chave vai no cabeçalho `Authorization` de toda requisição:

```bash theme={null}
curl https://api.t3sa.com/v1/posicoes \
  -H "Authorization: Bearer tesa_live_..."
```

<Warning>
  A chave de API autentica a integração com a TESA. Ela não assina transações e não dá acesso às chaves da carteira, que continuam com a empresa ou o seu custodiante.
</Warning>

## Escopos

Cada chave recebe um ou mais escopos. Uma chamada fora do escopo retorna `403`.

| Escopo | Permite |
| - | - |
| `read` | Ler organização, carteiras, posições, política, propostas, resgates, registros, rendimento e cobranças |
| `propose` | Criar propostas de rebalanceamento e solicitações de resgate, que ficam pendentes de aprovação |
| `admin` | Aprovar ou rejeitar propostas, alterar a política de alocação, vincular carteiras e gerenciar webhooks |

A recomendação é separar funções: a integração do ERP usa `read` e `propose`, e a aprovação fica com uma chave `admin` guardada em ambiente restrito, ou apenas no painel.

## Rotação

* Uma organização pode ter mais de uma chave ativa ao mesmo tempo, o que permite rotação sem janela de indisponibilidade.
* O fluxo sugerido é criar a nova chave, atualizar a integração e revogar a antiga.
* Chaves revogadas deixam de funcionar na hora. Cada chave registra data de criação, último uso e autor.

## Allowlist de IP

Chaves de produção podem ser restritas a uma lista de IPs ou blocos CIDR. Requisições de fora da lista retornam `403` com o código `ip_nao_autorizado`. A proposta é tornar a allowlist obrigatória para chaves com escopo `admin`.

## Assinatura de requisição (HMAC)

Além da chave, requisições que alteram estado (`POST`, `PUT`) podem ser assinadas com um segredo HMAC da organização, distinto da chave de API. A proposta é que a assinatura seja obrigatória para chaves com escopo `admin`.

| Cabeçalho | Conteúdo |
| - | - |
| `Tesa-Timestamp` | Momento da requisição em segundos Unix |
| `Tesa-Signature` | HMAC-SHA256 em hexadecimal da mensagem canônica |

A mensagem canônica junta, separados por quebra de linha: o timestamp, o método, o caminho com query string e o corpo bruto da requisição.

```text theme={null}
1788220800
POST
/v1/propostas/prop_8f2a1c/aprovar
{"comentario":"Aprovado pela tesouraria"}
```

Requisições com timestamp fora de uma janela de 5 minutos são recusadas com `401`, o que impede reenvio de uma requisição capturada.

## Idempotência

Toda requisição `POST` aceita o cabeçalho `Idempotency-Key`, com um valor único gerado pela integração (um UUID, por exemplo).

* Repetir a mesma chave com o mesmo corpo devolve a resposta original, sem criar uma segunda operação.
* Repetir a mesma chave com corpo diferente retorna `409` com o código `conflito_idempotencia`.
* As chaves ficam guardadas por 24 horas.

<Note>
  Em resgates e aprovações, o uso de `Idempotency-Key` é obrigatório. Uma falha de rede não deve gerar duas solicitações de resgate.
</Note>

## Limites de taxa

Os limites valem por chave e são detalhados em [Erros e limites](/docs/api/erros-e-limites). Toda resposta traz os cabeçalhos `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset`.