Autenticación

Cada llamada a Retorna Gateway lleva dos capas independientes. Esta página cubre la primera; la segunda tiene su propia guía.

Capa	Qué prueba	Dónde
Aplicación	Tu access token	esta página
Integridad	La firma de la request	Firma de solicitudes

Obtener un token

POST /oauth2/token con el grant OAuth2 client_credentials. El par clientId / clientSecret viaja en un header Authorization: Basic, y el scope en un body form-encoded:

curl -X POST https://api.gateway.sandbox.retorna.app/oauth2/token \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "scope=sandbox/full_access"

El scope es fijo por ambiente: sandbox/full_access en sandbox y prod/full_access en producción. No hay scopes más granulares: el par de credenciales ya define lo que tu compañía puede hacer.

{
  "access_token": "eyJraWQiOiJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Y después va en cada llamada siguiente:

Authorization: Bearer eyJraWQiOiJ...

Lo que esto NO es

Es autenticación máquina a máquina, no un login de usuario. No hay email, no hay password, no hay idToken y no hay refresh token — cuando el token expira pides otro igual que el primero. Trata el par de credenciales como una API key: identifica a tu compañía, no a una persona.

Por eso mismo ningún endpoint recibe un parámetro de cuenta, owner o compañía. Tu compañía se resuelve del token verificado, así que GET /me/wallets/{currency} y GET /me/routes no reciben ningún parámetro de compañía para saber de quién es la wallet y cuáles son los corredores. Una credencial, una compañía.

Vigencia del token

expires_in viene en segundos — 3600 en el ejemplo de arriba, pero lee el campo en vez de hardcodear una hora. Guarda el token en caché y reutilízalo hasta que esté cerca de expirar, en lugar de pedir uno por llamada.

Cuando falla

Un 401 en /oauth2/token cubre cualquier problema de credenciales: header Authorization ausente, un esquema distinto de Basic, base64 que no decodifica a clientId:clientSecret, secret equivocado, o un scope para el que tus credenciales no fueron habilitadas.

Un 401 en cualquier otro endpoint significa que el rechazado fue el token — ausente, malformado, expirado o inválido para el canal. El body distingue los dos casos:

{ "message": "Bearer token required", "error": "Unauthorized", "statusCode": 401 }
{ "message": "Invalid api token",     "error": "Unauthorized", "statusCode": 401 }

Un token válido no alcanza por sí solo: la mayoría de los endpoints además pide firma. Si el token está bien y sigues recibiendo 401, lee firma de solicitudes — desde afuera las dos fallas se ven idénticas.