> ## 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ón

> Cómo autenticarse en la API de YoFacturo.

## Descripción general

YoFacturo utiliza un **flujo de autenticación en dos pasos**:

1. Intercambia la `api_key` de tu organización por un `session_token` de corta duración.
2. Incluye el `session_token` como **Bearer token** en la cabecera `Authorization` de cada solicitud posterior.

## Crear un token de sesión

Intercambia tu `api_key` por un `session_token` válido durante **24 horas**.

### Endpoint

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

### Solicitud

<ParamField body="api_key" type="string" required>
  La API key de tu organización.
</ParamField>

### Ejemplo

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

### Respuesta

Este endpoint devuelve un objeto JSON plano — sin envelope `data`.

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

| Campo           | Tipo              | Descripción                                                  |
| --------------- | ----------------- | ------------------------------------------------------------ |
| `session_token` | string            | Bearer token para usar en solicitudes posteriores            |
| `expires_at`    | datetime ISO 8601 | Momento de expiración del token (24 horas desde su creación) |

### Respuestas de error

| Estado | Código         | Causa                                                                                    |
| ------ | -------------- | ---------------------------------------------------------------------------------------- |
| `400`  | `bad_request`  | El parámetro `api_key` está ausente, es null o está vacío                                |
| `401`  | `unauthorized` | La `api_key` proporcionada es inválida o ha sido revocada — mensaje: `"Invalid API key"` |

## Autenticar solicitudes

Incluye el `session_token` en la cabecera `Authorization` como **Bearer token** en todos los endpoints protegidos:

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

Si la cabecera `Authorization` está ausente, la API devuelve `401 Unauthorized`:

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

Si el token es inválido o ha expirado, la API devuelve `401 Unauthorized`:

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

## Expiración y renovación del token

Los tokens de sesión expiran **24 horas** después de su creación. No existe mecanismo de refresco — simplemente solicita un nuevo token llamando a `POST /api/v1/auth/sessions` de nuevo con tu `api_key`.

Recomendamos almacenar el timestamp `expires_at` y renovar el token de forma proactiva antes de que expire para evitar solicitudes fallidas.