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

# Authentication

> How to authenticate API requests, and why your API key must stay on your server.

The Eclatira API uses API keys. Send your key in the `Authorization` header of every request:

```bash theme={"system"}
Authorization: Bearer ek_your_api_key_here
```

A missing or invalid key returns `401 Unauthorized`.

## Get an API key

Create keys in the dashboard under **Settings → API Keys**. You need the `developer` role or higher.

* The full key is shown **once**, when you create it. Save it right away.
* You cannot see a key again later. You can only revoke it and create a new one.
* Each key belongs to one workspace. It can only see and change that workspace's agents, calls and data.

## Keep your key on the server

An API key has **no scopes**. Any key can do everything in its workspace. It can delete agents, place phone calls that cost money, and read every transcript. There are no read-only keys and no per-agent keys.

So treat the key like a password:

* Store it in an environment variable or a secret manager on your server.
* Never put it in browser code, a mobile app, or a `NEXT_PUBLIC_` variable.
* Never commit it to a repository.

<Warning>
  **Browser sessions need your own backend.** The browser cannot call the Eclatira API directly. The API only accepts browser requests from a fixed list of origins. That list includes `http://localhost:3000`, so a browser-only setup seems to work on your laptop. It then fails with a CORS error as soon as you deploy.

  Instead, your server creates the session and gives the browser a short-lived link. See [How web sessions work](/realtime/overview).
</Warning>

## Session tokens for the browser

To start a web session, your server calls `POST /api/v1/realtime/sessions` with the API key. The response has a `session_token` and a `ws_url`. It is safe to send these to the browser because the token:

* expires after **60 seconds**
* works for **one connection only**
* only works for one agent and one `user_id`

## Managing keys through the API

The key endpoints (`POST /api/v1/keys`, `GET /api/v1/keys` and `DELETE /api/v1/keys/{key_id}`) do not accept an API key. They need a dashboard login session instead:

```bash theme={"system"}
Authorization: Bearer <dashboard-session-token>
```

This stops a leaked key from creating more keys. It also means a pure server-to-server setup cannot create its first key. Someone must log in to the dashboard at least once.

## Related

<CardGroup cols={2}>
  <Card title="Verify webhooks" icon="shield-check" href="/webhooks#verify-the-signature">
    Check that a webhook really came from Eclatira.
  </Card>

  <Card title="API key endpoints" icon="code" href="/api-reference/developer-api-keys/create-an-api-key">
    Create, list and revoke keys.
  </Card>
</CardGroup>


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