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



The API has **two distinct credentials**, and they are not interchangeable. Which
one you use depends on where your code runs and what data it needs to see.

## Commerce API key
This is the classic integration: your backend operates across every member of the
commerce. The API key goes in the `Authorization` header:

```
Authorization: Bearer {api-key}
```

This credential works with [Consumptions](https://docs.loybox.com.ar/api-reference/consumos),
[Benefits](https://docs.loybox.com.ar/api-reference/beneficios) and [Clients](https://docs.loybox.com.ar/api-reference/clientes). No
other header is needed: the key already identifies the commerce.

<Callout type="warn" title="It is a secret">
  The API key grants access to the data of **all** your members. Never put it in the
  frontend, in a mobile app, or in a repository. If it leaked, write to us at
  [hola@loybox.com.ar](mailto:hola@loybox.com.ar) so we can rotate it.
</Callout>

## End-user token
Meant for wiring Loybox straight into your frontend and using it as a loyalty
engine: the user signs in with a code emailed to them and from there looks up
their points, buys benefits and sees their history.

Two headers travel:

```
Authorization: Bearer {user-access-token}
X-Commerce-Id: {your-commerce-id}
```

This credential works with [Authentication](https://docs.loybox.com.ar/api-reference/autenticacion),
[My account](https://docs.loybox.com.ar/api-reference/mi-cuenta) and [Public](https://docs.loybox.com.ar/api-reference/publico). This
token **can** live in the browser: it only sees that user's data in your commerce.

## The X-Commerce-Id header
<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id of the commerce integrating the API. Every response is scoped to this
    commerce.
  </Field>
</Fields>

It is required on **every** Authentication, My account and Public endpoint, even
the ones that carry no token. It is the header that scopes the response to your
program: the same user can be in several Loybox programs, and with this header
they only see yours.

It is not a secret: it goes in the frontend without a problem. What it does is
scope, not authorize.

## The sign-in flow
<Steps>
  <Step>
    ### Request the code
    [`POST /v1/auth/otp/request`](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo) with the
    user's email. They receive a 6-digit code.
  </Step>

  <Step>
    ### Verify it
    [`POST /v1/auth/otp/verify`](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo) with
    the email and the code. It returns an access token (`access`) and a refresh token
    (`refresh`). If the email had no Loybox account, one is created, and either way
    the user ends up subscribed to your commerce's program.
  </Step>

  <Step>
    ### Use the session
    From there on, calls to [My account](https://docs.loybox.com.ar/api-reference/mi-cuenta) go with
    `Authorization: Bearer {access}`.
  </Step>

  <Step>
    ### Renew it
    When the `access` expires,
    [`POST /v1/auth/refresh`](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) returns a
    new one from the `refresh`, without asking the user for another code.
  </Step>
</Steps>

The code expires in **10 minutes** and allows **5 attempts**. Requesting a new
code invalidates the previous one.

## Summary
|                    | Commerce API key                  | End-user token                                     |
| ------------------ | --------------------------------- | -------------------------------------------------- |
| **Header**         | `Authorization: Bearer {api-key}` | `Authorization: Bearer {access}` + `X-Commerce-Id` |
| **Where it lives** | On your server only               | Can live in the browser                            |
| **What it sees**   | Every member of the commerce      | Only that user, only in your commerce              |
| **Expires**        | No                                | Yes, renewed with the `refresh`                    |
| **Sections**       | Consumptions, Benefits, Clients   | Authentication, My account, Public                 |