Credenciales
Las dos credenciales de la API, qué headers lleva cada llamada y cuál puede vivir en el browser.
La API tiene dos credenciales distintas, y no son intercambiables. Cuál usás depende de dónde corre tu código y de qué datos necesita ver.
API key del comercio
Es la integración clásica: tu backend opera sobre todos los clientes del
comercio. La API key va en el header Authorization:
Authorization: Bearer {api-key}Con esta credencial funcionan Consumos, Beneficios y Clientes. No hace falta ningún otro header: la key ya identifica al comercio.
Es secreta
La API key da acceso a los datos de todos tus clientes. No la pongas nunca en el frontend, en una app móvil, ni en un repositorio. Si se filtró, escribinos a hola@loybox.com.ar para rotarla.
Token del usuario final
Pensada para conectar Loybox directo al frontend y usarlo como motor de fidelidad: el usuario inicia sesión con un código que le llega por email y a partir de ahí consulta sus puntos, compra beneficios y ve su historial.
Van dos headers:
Authorization: Bearer {access-token-del-usuario}
X-Commerce-Id: {tu-commerce-id}Con esta credencial funcionan Autenticación, Mi cuenta y Público. Este token sí puede vivir en el browser: sólo ve los datos de ese usuario en tu comercio.
El header X-Commerce-Id
X-Commerce-IdintegerheaderrequeridoId del comercio que integra la API. Todas las respuestas quedan limitadas a este comercio.
Es obligatorio en todos los endpoints de Autenticación, Mi cuenta y Público, incluso en los que no llevan token. Es el header que acota la respuesta a tu programa: un mismo usuario puede estar en varios programas de Loybox y con este header ve sólo el tuyo.
No es un secreto: va en el frontend sin problema. Lo que hace es delimitar, no autorizar.
El flujo de login
Pedir el código
POST /v1/auth/otp/request con el
email del usuario. Le llega un código de 6 dígitos.
Verificarlo
POST /v1/auth/otp/verify con
el email y el código. Devuelve un token de acceso (access) y uno de refresco
(refresh). Si el email no tenía cuenta en Loybox se crea, y en ambos casos el
usuario queda adherido al programa de tu comercio.
Usar la sesión
A partir de ahí, las llamadas a Mi cuenta van con
Authorization: Bearer {access}.
Renovarla
Cuando el access vence,
POST /v1/auth/refresh devuelve
uno nuevo a partir del refresh, sin pedirle otro código al usuario.
El código vence a los 10 minutos y admite 5 intentos. Pedir un código nuevo invalida el anterior.
Resumen
| API key del comercio | Token del usuario final | |
|---|---|---|
| Header | Authorization: Bearer {api-key} | Authorization: Bearer {access} + X-Commerce-Id |
| Dónde vive | Sólo en tu servidor | Puede vivir en el browser |
| Qué ve | Todos los clientes del comercio | Sólo ese usuario, sólo en tu comercio |
| Vence | No | Sí, se renueva con el refresh |
| Secciones | Consumos, Beneficios, Clientes | Autenticación, Mi cuenta, Público |