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



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 [#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ó, escribinos
  a [hola@loybox.com.ar](mailto:hola@loybox.com.ar) para rotarla.
</Callout>

## Token del usuario final [#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](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 browser**: sólo ve los datos de ese usuario en tu
comercio.

## El header X-Commerce-Id [#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 login [#el-flujo-de-login]

<Steps>
  <Step>
    ### Pedir el código [#pedir-el-código]

    [`POST /v1/auth/otp/request`](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo) con el
    email del usuario. Le llega un código de 6 dígitos.
  </Step>

  <Step>
    ### Verificarlo [#verificarlo]

    [`POST /v1/auth/otp/verify`](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo) 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.
  </Step>

  <Step>
    ### Usar la sesión [#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 [#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 [#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                  |