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

# Autenticación

> Claves de API, alcances, rotación, lista de IP permitidas, firma de solicitudes e idempotencia

> [!WARNING]
>
> Borrador: especificación en curso. Los endpoints y campos pueden cambiar.

## Claves de API

Cada clave pertenece a una organización y es creada en el panel por un administrador. La clave completa se muestra una sola vez, al momento de crearla.

| Prefijo | Entorno |
| - | - |
| `tesa_test_` | Sandbox |
| `tesa_live_` | Producción |

La clave va en el encabezado `Authorization` de cada solicitud:

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

> [!WARNING]
>
> La clave de API autentica la integración ante TESA. No firma transacciones ni da acceso a las claves de las billeteras, que permanecen con la empresa o con su custodio.

## Alcances

Cada clave recibe uno o más alcances. Una llamada fuera del alcance de la clave devuelve `403`.

| Alcance | Permite |
| - | - |
| `read` | Leer organización, billeteras, posiciones, política, propuestas, rescates, registros, rendimiento y facturas de uso |
| `propose` | Crear propuestas de rebalanceo y solicitudes de rescate, que quedan pendientes de aprobación |
| `admin` | Aprobar o rechazar propuestas, cambiar la política de asignación, vincular billeteras y administrar webhooks |

Recomendamos separar funciones: la integración con el ERP usa `read` y `propose`, y la aprobación queda con una clave `admin` guardada en un entorno restringido, o solo en el panel.

## Rotación

* Una organización puede tener más de una clave activa a la vez, lo que permite rotar sin ventana de interrupción.
* El flujo sugerido es crear la nueva clave, actualizar la integración y revocar la anterior.
* Las claves revocadas dejan de funcionar de inmediato. Cada clave registra su fecha de creación, último uso y autor.

## Lista de IP permitidas

Las claves de producción pueden restringirse a una lista de IP o bloques CIDR. Las solicitudes desde fuera de la lista devuelven `403` con el código `ip_nao_autorizado`. La propuesta es que la lista de IP permitidas sea obligatoria para las claves con alcance `admin`.

## Firma de solicitudes (HMAC)

Además de la clave, las solicitudes que cambian estado (`POST`, `PUT`) pueden firmarse con un secreto HMAC de la organización, separado de la clave de API. La propuesta es que la firma sea obligatoria para las claves con alcance `admin`.

| Encabezado | Contenido |
| - | - |
| `Tesa-Timestamp` | Hora de la solicitud en segundos Unix |
| `Tesa-Signature` | HMAC-SHA256 en hexadecimal del mensaje canónico |

El mensaje canónico une, separados por saltos de línea: la marca de tiempo, el método, la ruta con la cadena de consulta y el cuerpo bruto de la solicitud.

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

Las solicitudes con una marca de tiempo fuera de una ventana de 5 minutos se rechazan con `401`, lo que impide la repetición de una solicitud capturada.

## Idempotencia

Toda solicitud `POST` acepta el encabezado `Idempotency-Key`, con un valor único generado por la integración (un UUID, por ejemplo).

* Repetir la misma clave con el mismo cuerpo devuelve la respuesta original, sin crear una segunda operación.
* Repetir la misma clave con un cuerpo distinto devuelve `409` con el código `conflito_idempotencia`.
* Las claves se almacenan durante 24 horas.

> [!NOTE]
>
> Para rescates y aprobaciones, `Idempotency-Key` es obligatoria. Una falla de red no debe crear dos solicitudes de rescate.

## Límites de tasa

Los límites se aplican por clave y se detallan en [Errores y límites](https://t3sa.com/docs/es/api/erros-e-limites.md). El volumen de llamadas es además la base de la factura de uso del plan: vea [Precios y uso](https://t3sa.com/docs/es/api/taxas.md). Toda respuesta incluye los encabezados `RateLimit-Limit`, `RateLimit-Remaining` y `RateLimit-Reset`.


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