> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yofacturo.es/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticació

> Com autenticar-se a l'API de YoFacturo.

## Descripció general

YoFacturo utilitza un **flux d'autenticació en dos passos**:

1. Intercanvia l'`api_key` de la teva organització per un `session_token` de curta durada.
2. Inclou el `session_token` com a **Bearer token** a la capçalera `Authorization` de cada sol·licitud posterior.

## Crear un token de sessió

Intercanvia la teva `api_key` per un `session_token` vàlid durant **24 hores**.

### Endpoint

```
POST /api/v1/auth/sessions
```

### Sol·licitud

<ParamField body="api_key" type="string" required>
  L'API key de la teva organització.
</ParamField>

### Exemple

```bash theme={null}
curl -X POST https://app.yofacturo.es/api/v1/auth/sessions \
  -H "Content-Type: application/json" \
  -d '{"api_key": "la_teva_api_key_aqui"}'
```

### Resposta

Aquest endpoint retorna un objecte JSON pla — sense envelope `data`.

```json theme={null}
{
  "session_token": "H2sY0Qw_example_8eA",
  "expires_at": "2026-03-27T10:30:00Z"
}
```

| Camp            | Tipus             | Descripció                                                     |
| --------------- | ----------------- | -------------------------------------------------------------- |
| `session_token` | string            | Bearer token per usar en sol·licituds posteriors               |
| `expires_at`    | datetime ISO 8601 | Moment d'expiració del token (24 hores des de la seva creació) |

### Respostes d'error

| Estat | Codi           | Causa                                                                                     |
| ----- | -------------- | ----------------------------------------------------------------------------------------- |
| `400` | `bad_request`  | El paràmetre `api_key` és absent, null o buit                                             |
| `401` | `unauthorized` | L'`api_key` proporcionada és invàlida o ha estat revocada — missatge: `"Invalid API key"` |

## Autenticar sol·licituds

Inclou el `session_token` a la capçalera `Authorization` com a **Bearer token** a tots els endpoints protegits:

```bash theme={null}
curl https://app.yofacturo.es/api/v1/invoice_batches \
  -H "Authorization: Bearer H2sY0Qw_example_8eA"
```

Si la capçalera `Authorization` és absent, l'API retorna `401 Unauthorized`:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Missing Authorization header"
  }
}
```

Si el token és invàlid o ha expirat, l'API retorna `401 Unauthorized`:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired session token"
  }
}
```

## Expiració i renovació del token

Els tokens de sessió expiren **24 hores** després de la seva creació. No existeix mecanisme de refresc — simplement sol·licita un nou token cridant `POST /api/v1/auth/sessions` de nou amb la teva `api_key`.

Recomanem emmagatzemar el timestamp `expires_at` i renovar el token de manera proactiva abans que expiri per evitar sol·licituds fallides.