Autenticación

Manda tu API key en el header x-api-key, en todas las llamadas y sobre HTTPS.

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

200 OK

{
  "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 no requiere scope: devuelve el contexto de la propia clave.

Modo test y modo live

Prefijo	mode	Qué hace
sk_test_…	test	Sólo enruta a proveedores de prueba. No mueve dinero real
sk_live_…	live	Producción

El contrato es idéntico en los dos. Ver entorno de pruebas.

Scopes

Scope	Permite
quotes:write	POST /quotes · GET /quotes/{id}
beneficiaries:write	POST /beneficiaries
beneficiaries:read	GET /beneficiaries · GET /beneficiaries/{id}
payments:write	POST /payouts — dispersar
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

Un endpoint pide uno de los scopes que declara, no todos. Si a la clave le falta:

403 Forbidden

{ "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"] } } }

Errores de autenticación

error.code	HTTP	Qué pasó
api_key_missing	401	Falta el header x-api-key
api_key_invalid	401	La clave no existe
api_key_revoked	401	Se revocó
api_key_expired	401	Caducó
tenant_suspended	403	Tu programa está suspendido. Contacta a soporte
insufficient_scope	403	La clave no tiene el permiso. meta.required dice cuál

Un recurso de otro programa devuelve 404, no 403.

Rotación sin downtime

Puedes tener varias claves activas a la vez. La emisión y la revocación las hacemos nosotros: te devolvemos la nueva antes de retirar la anterior. Si una se filtra, avísanos y la revocamos en el momento; las demás siguen operando.

Límite de peticiones

300 peticiones por minuto, por programa y no por IP. Cada respuesta trae:

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

Al superarlo, 429 con error.code: "rate_limited" y cabecera Retry-After.

request_id

Toda respuesta lleva la cabecera x-request-id, y los errores lo repiten en error.request_id. Si lo mandas tú, lo respetamos. Inclúyelo al abrir un ticket.

Registro de acciones

Toda acción atribuible a una credencial queda en un registro append-only —claves, límites, tarifas, acreditaciones de liquidez—, con identificadores y metadatos: nunca datos personales ni secretos.