Autenticación

Modelo de credenciales, flujo de refresh del token y guía de seguridad para la API de Cobru.

Cobru usa un modelo de autenticación por capas:

x-api-key: tu llave de integración
Authorization: Bearer {access}: token de acceso de corta duración obtenido desde /token/refresh/

Empieza aquí

Guarda x-api-key y el token refresh solo en almacenamiento secreto backend.
Emite un access token desde /token/refresh/.
Cachea ese access token de forma centralizada antes de hacer llamadas rutinarias.
Reúsalo hasta que toque refrescarlo en lugar de emitirlo en cada request.

Rol de cada credencial

Credencial	Dónde usarla	Notas
`x-api-key`	requests backend	Trátala como credencial de integración y mantenla fuera de bundles frontend
token `refresh`	solo almacenamiento secreto backend	Se usa únicamente para emitir access tokens temporales
token `access`	requests backend	Cachearlo agresivamente y rotarlo con frecuencia

Flujo de refresh del token

curl -X POST https://dev.cobru.co/token/refresh/ \
  -H "x-api-key: $COBRU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refresh":"'"$COBRU_REFRESH_TOKEN"'"}'

Respuesta esperada

{ "access": "eyJ0eXAi..." }

El campo del body es refresh, no refresh_token. Esta discrepancia es uno de los quirks más importantes de Cobru y debe quedar muy visible para el equipo.

Headers requeridos para requests API

x-api-key: {tu_api_key}
Authorization: Bearer {access}
Accept: application/json
Content-Type: application/json

Vida útil del token y caché

Propiedad	Recomendación
vida útil observada del token	cerca de 60 minutos
TTL seguro de caché	50 minutos
caveat en Edge runtime	los caches en memoria no persisten entre invocaciones
fix de producción	guardar el token en Redis, Vercel KV u otro caché compartido

Variables de entorno

COBRU_BASE_URL=https://dev.cobru.co
COBRU_API_KEY=...
COBRU_REFRESH_TOKEN=...

Checklist de seguridad

Mantén todas las credenciales Cobru solo en variables de entorno del servidor.
Nunca envíes x-api-key al navegador ni a clientes móviles.
Refresca el access token desde el servidor, no desde el frontend.
Rota credenciales cuando cambie el equipo con acceso.
Usa URLs callback con HTTPS en producción.

Sigue con

/docs/getting-started
/docs/webhooks
/docs/api/authentication/refresh

Autenticación

On this page