Authentication

Send your API key in the x-api-key header, on every call and over HTTPS.

curl -s $BASE/v1/tenant/me -H "x-api-key: sk_live_..."

{
  "tenantId": "3f1a0c22-9b41-4a77-8f0e-6d2c5b7a1e34", "name": "Fintech Ejemplo",
  "mode": "live",
  "scopes": ["quotes:write", "beneficiaries:read", "beneficiaries:write",
             "payments:read", "payments:write", "treasury:read",
             "events:read", "events:write"],
  "apiKeyId": "5c9d2b70-1f44-4c8e-9a3b-2e7f0d5a6b18", "isPlatform": false
}

GET /v1/tenant/me requires no scope: it returns the context of the key itself.

Test mode and live mode

Prefix	`mode`	What it does
`sk_test_…`	`test`	Only routes to simulated payment networks. It does not move real money
`sk_live_…`	`live`	Production

The contract is identical in both. See test environment.

Scopes

Scope	Allows
`quotes:write`	`POST /quotes` · `GET /quotes/{id}`
`beneficiaries:write`	`POST /beneficiaries`
`beneficiaries:read`	`GET /beneficiaries` · `GET /beneficiaries/{id}`
`payments:write`	`POST /payouts` — pay out
`payments:read`	`GET /payments` · `GET /payments/{id}` · `GET /payouts/banks` · `GET /limits/usage` · `GET /quotes/{id}`
`treasury:read`	`GET /treasury/position`
`events:read`	`GET /events` · `GET /events/{id}`
`events:write`	`POST /events/{id}/retry` · `POST /events/retry-dead`

An endpoint requires one of the scopes it declares, not all of them. If the key is missing it:

{ "error": {
    "type": "authentication_error", "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope necesario (requiere uno de: payments:write)",
    "request_id": "req_8a0312ba896772bc441134cd",
    "meta": { "required": ["payments:write"] } } }

message comes in Spanish; code and meta.required are what you program against.

Authentication errors

`error.code`	HTTP	What happened
`api_key_missing`	401	The `x-api-key` header is missing
`api_key_invalid`	401	The key does not exist
`api_key_revoked`	401	It was revoked
`api_key_expired`	401	It expired
`tenant_suspended`	403	Your program is suspended. Contact support
`insufficient_scope`	403	The key lacks the permission. `meta.required` says which

A resource from another program returns 404, not 403.

Zero-downtime rotation

You can have several keys active at the same time. We handle issuing and revoking them: we give you the new one before retiring the old one. If one leaks, let us know and we revoke it on the spot; the others keep working.

Rate limit

300 requests per minute, per program and not per IP. Every response carries:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 41

When you exceed it, 429 with error.code: "rate_limited" and a Retry-After header.

`request_id`

Every response carries the x-request-id header, and errors repeat it in error.request_id. If you send it yourself, we keep it. Include it when you open a ticket.

Action log

Every action attributable to a credential is recorded in an append-only log —keys, limits, fees, liquidity credits—, with identifiers and metadata: never personal data or secrets.