> ## 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.

# Authentication

> How to authenticate against the YoFacturo API.

## Overview

YoFacturo uses a **two-step authentication flow**:

1. Exchange your organization's `api_key` for a short-lived `session_token`.
2. Include the `session_token` as a **Bearer token** in the `Authorization` header of every subsequent request.

## Create a session token

Exchange your `api_key` for a `session_token` valid for **24 hours**.

### Endpoint

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

### Request

<ParamField body="api_key" type="string" required>
  Your organization's API key.
</ParamField>

### Example

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

### Response

This endpoint returns a flat JSON object — no `data` envelope.

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

| Field           | Type              | Description                                       |
| --------------- | ----------------- | ------------------------------------------------- |
| `session_token` | string            | Bearer token to use in subsequent requests        |
| `expires_at`    | ISO 8601 datetime | Expiry time of the token (24 hours from issuance) |

### Error responses

| Status | Code           | Cause                                                                                |
| ------ | -------------- | ------------------------------------------------------------------------------------ |
| `400`  | `bad_request`  | `api_key` parameter is missing, null, or empty                                       |
| `401`  | `unauthorized` | The provided `api_key` is invalid or has been revoked — message: `"Invalid API key"` |

## Authenticate requests

Include the `session_token` in the `Authorization` header as a **Bearer token** for all protected endpoints:

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

If the `Authorization` header is missing, the API returns `401 Unauthorized`:

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

If the token is invalid or expired, the API returns `401 Unauthorized`:

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

## Token expiry and renewal

Session tokens expire **24 hours** after creation. There is no refresh mechanism — simply request a new token by calling `POST /api/v1/auth/sessions` again with your `api_key`.

We recommend storing the `expires_at` timestamp and proactively renewing the token before it expires to avoid failed requests.