Skip to main content
Draft: specification in progress. Endpoints and fields may change.

​
API keys

Each key belongs to an organization and is created in the dashboard by an administrator. The full key is shown only once, at creation. The key goes in the Authorization header of every request:
The API key authenticates the integration with TESA. It does not sign transactions and does not grant access to the wallet keys, which remain with the company or its custodian.

​
Scopes

Each key receives one or more scopes. A call outside the key’s scope returns 403. We recommend separating duties: the ERP integration uses read and propose, and approval stays with an admin key kept in a restricted environment, or in the dashboard only.

​
Rotation

  • An organization can have more than one active key at a time, which allows rotation with no downtime window.
  • The suggested flow is to create the new key, update the integration and revoke the old one.
  • Revoked keys stop working immediately. Each key records its creation date, last use and author.

​
IP allowlist

Production keys can be restricted to a list of IPs or CIDR blocks. Requests from outside the list return 403 with the code ip_nao_autorizado. The proposal is to make the allowlist mandatory for keys with admin scope.

​
Request signing (HMAC)

In addition to the key, state-changing requests (POST, PUT) can be signed with an organization HMAC secret, separate from the API key. The proposal is to make signing mandatory for keys with admin scope. The canonical message joins, separated by line breaks: the timestamp, the method, the path with query string and the raw request body.
Requests with a timestamp outside a 5-minute window are rejected with 401, which prevents replay of a captured request.

​
Idempotency

Every POST request accepts the Idempotency-Key header, with a unique value generated by the integration (a UUID, for example).
  • Repeating the same key with the same body returns the original response, without creating a second operation.
  • Repeating the same key with a different body returns 409 with the code conflito_idempotencia.
  • Keys are stored for 24 hours.
For redemptions and approvals, Idempotency-Key is mandatory. A network failure must not create two redemption requests.

​
Rate limits

Limits apply per key and are detailed in Errors and limits. Every response includes the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers.