# Credenciales (https://docs.loybox.com.ar/es-419/api-reference/credenciales)



La API tiene **dos credenciales distintas**, y no son intercambiables. Cuál usas
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](https://docs.loybox.com.ar/api-reference/consumos),
[Beneficios](https://docs.loybox.com.ar/api-reference/beneficios) y [Clientes](https://docs.loybox.com.ar/api-reference/clientes).
No hace falta ningún otro header: la key ya identifica al comercio.

<Callout type="warn" title="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ó, escríbenos
  a [hola@loybox.com.ar](mailto:hola@loybox.com.ar) para rotarla.
</Callout>

## Token del usuario final
Pensada para conectar Loybox directo al frontend y usarlo como motor de
lealtad: el usuario inicia sesión con un código que le llega por correo 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](https://docs.loybox.com.ar/api-reference/autenticacion),
[Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) y [Público](https://docs.loybox.com.ar/api-reference/publico). Este
token **sí puede vivir en el navegador**: sólo ve los datos de ese usuario en tu
comercio.

## El header X-Commerce-Id
<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

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 inicio de sesión
<Steps>
  <Step>
    ### Pedir el código
    [`POST /v1/auth/otp/request`](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo) con el
    correo del usuario. Le llega un código de 6 dígitos.
  </Step>

  <Step>
    ### Verificarlo
    [`POST /v1/auth/otp/verify`](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo) con
    el correo y el código. Devuelve un token de acceso (`access`) y uno de refresco
    (`refresh`). Si el correo no tenía cuenta en Loybox se crea, y en ambos casos el
    usuario queda adherido al programa de tu comercio.
  </Step>

  <Step>
    ### Usar la sesión
    A partir de ahí, las llamadas a [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) van con
    `Authorization: Bearer {access}`.
  </Step>

  <Step>
    ### Renovarla
    Cuando el `access` vence,
    [`POST /v1/auth/refresh`](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) devuelve
    uno nuevo a partir del `refresh`, sin pedirle otro código al usuario.
  </Step>
</Steps>

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 navegador                        |
| **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                  |