Autenticación

Toda petición a la API (excepto GET /status) lleva tu API key como Bearer token:

Authorization: Bearer agk_0123456789abcdef0123456789abcdef0123456789abcdef

La llave

Aspecto	Detalle
Formato	`agk_` + 48 caracteres hexadecimales en minúsculas (`^agk_[0-9a-f]{48}$`).
Quién la emite	El administrador de Gate, desde su panel, asociada a tu proveedor y con una etiqueta descriptiva.
Se muestra	Una sola vez. En nuestra base solo vive un hash SHA-256 y los últimos 4 caracteres para identificarla.
Uso	Header `Authorization: Bearer <llave>`. No hay otra forma de enviarla (ni query string ni body).
Alcance	Tu proveedor completo: todas las experiencias que Gate haya enlazado a él.

Cada uso válido actualiza la fecha de “último uso” de la llave, visible para el admin de Gate.

Llaves `h4fk_` emitidas antes del rename

Antes del 2026-09-01 el producto se llamaba h4f y las llaves se emitían con el prefijo h4fk_. Esas llaves siguen siendo válidas hasta el 2026-12-01: la API las acepta exactamente igual que a las agk_ (mismo alcance, mismo rate limit, mismos errores).

A partir del 2026-12-01 toda llave h4fk_ responde 401 KEY_INVALID.
Pide al administrador una llave agk_ nueva, despliégala en tu integración y después revoca la h4fk_. Ambas pueden convivir, así que la rotación no requiere ventana de mantenimiento (ver rotación).
Las llaves nuevas se emiten únicamente con prefijo agk_.

Revocación y rotación

El admin de Gate puede revocar una llave en cualquier momento; a partir de ese instante responde 401 KEY_INVALID.
Si el admin desactiva tu proveedor, todas tus llaves responden 401 KEY_INVALID.
Para rotar, pide al admin una llave nueva, cámbiala en tu integración y después pide revocar la anterior. Varias llaves pueden convivir, así que la rotación no requiere ventana de mantenimiento.
Si sospechas una filtración, pide la revocación de inmediato.

Errores de autenticación

HTTP	`code`	Cuándo
401	`KEY_INVALID`	Header ausente, sin el prefijo `Bearer` , formato incorrecto, llave desconocida, revocada, o proveedor desactivado.

Por diseño no se distingue entre estos casos: el mensaje es el mismo (Invalid or revoked API key; Missing bearer API key si el header no viene).

{ "error": { "code": "KEY_INVALID", "message": "Invalid or revoked API key" } }

Rate limit

Cada ruta tiene un límite de 60 requests por minuto por llave. El contador es por llave + método + ruta declarada y por minuto de reloj:

Contador independiente
`POST /v1/partner/tickets/bulk`
`POST /v1/partner/tickets/void`
`GET /v1/partner/tickets/{ref}` (todos los `ref` comparten el mismo contador)
`GET /v1/partner/redemptions`

Al superar el límite recibes:

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests" } }

con HTTP 429. No enviamos header Retry-After: espera al siguiente minuto y reintenta con backoff. Para volúmenes grandes usa el bulk (1000 filas por request) en lugar de muchas peticiones pequeñas.

Buenas prácticas

Nunca en el cliente. La llave solo vive en tu servidor o gestor de secretos; no la incluyas en apps móviles, front-ends ni repositorios.
Una llave por integración (por ejemplo, una para tu backend de ventas y otra para tu job de reconciliación) facilita rotar y auditar.
Reintentos con backoff ante 429 y 500; nunca reintentes un 401 o 403 sin revisar la configuración.
TLS siempre. La API solo se sirve por HTTPS.