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

# Authentication

> API keys, receiving permissions and rate limits.

The REST API is available at:

```text theme={null}
https://talario.eu/api/v1
```

Every request needs an API key of your project as a bearer token:

```bash theme={null}
curl https://talario.eu/api/v1/receiving/messages \
  -H "Authorization: Bearer $TALARIO_API_KEY"
```

## API keys

Create API keys in the dashboard under **API keys**. A key is shown only once when it is created; Talario stores only a hash. Keys start with `tlr_api_`.

Keep API keys on your server. Never put them into a browser, a mobile app or a repository.

### Receiving permissions

A new API key cannot access received messages. Enable receiving access when you create the key, or later with **Change receiving access**:

| Permission | Allows |
| - | - |
| **Read received messages** | List messages, read metadata and parsed content, create download links |
| **Retry webhooks** | Request a new attempt of a failed or cancelled webhook delivery; requires **Read received messages** |

A key without the needed permission receives `403 forbidden`.

### Domain scope

A key for **all domains of this project** can access messages of every receiving domain of the project, including domains added later. A key for **selected domains only** can access only messages received for those domains. Messages of other domains or projects behave as if they did not exist: `404 not_found`.

## Rate limits

| Limit | Value |
| - | - |
| All API requests | 600 requests per minute and API key |
| `GET /receiving/messages/{id}/content` | additionally 60 requests per minute and API key |

When a limit is exceeded, the API answers with `429 too_many_requests` and a `Retry-After` header with the number of seconds to wait. Responses also carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`.

## Laravel client

A small HTTP client with Laravel's `Http` facade:

```php config/services.php theme={null}
'talario' => [
    'api_key' => env('TALARIO_API_KEY'),
],
```

```php theme={null}
use Illuminate\Support\Facades\Http;

$talario = Http::baseUrl('https://talario.eu/api/v1')
    ->withToken(config('services.talario.api_key'))
    ->acceptJson()
    ->timeout(30);

$messages = $talario->get('receiving/messages', ['limit' => 20])->throw()->json('data');
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.