# Authentication

Use a Reecall API key to authenticate requests from your backend. Send it as a Bearer token in the `Authorization` header. The dashboard and signed-in API reference can also use your account's access token.

## Get your first API key

1. Sign in to the [dashboard](https://dashboard.reecall.com) and select the Project your integration will use.
2. Open **Settings > API Keys** and create a key with a description that identifies its use, such as `Production backend`.
3. Copy the key's token and store it securely on your backend.

Select a Project before creating the key to restrict it to that Project. Creating a key requires key-management permissions. If you cannot create one, ask an administrator for access or a key for your integration.

:::warning{title="Keep API keys out of browser code"}

Do not include a Reecall API key in browser bundles, browser requests, or public repositories. Make Reecall API requests from your backend. For browser calls, pass only the returned LiveKit connection credentials to the client.

:::

## Authenticate a request

Use the token value, not the key record's `id`:

```http title="List available speech-to-speech models"
GET /data_next/ai/STS/
Authorization: Bearer {your-api-key}
```

The response is an array of available STS models. This request also checks that your key can authenticate without creating or changing resources.

Paths in this article include `/data_next` and are relative to your deployment host. The Data API server URL in the [API reference](/api) already includes this prefix, so do not append it twice. All IDs and tokens in the examples are placeholders.

## Key scopes

| Scope | `projectId` on the key | Access |
| --- | --- | --- |
| Project | A Project ID | Resources within that Project, plus shared catalogs such as AI models |
| Organization | `null` | Resources across Projects in the Organization, plus organization-level management endpoints |

Use a project-scoped key for an integration that only needs one Project. Use an organization-scoped key for provisioning or managing several Projects in the same Organization. Project-scoped keys cannot manage Projects or API keys.

### Creating project resources

For resources such as Assistants, Channels, and Hooks:

- A project-scoped key supplies `projectId` automatically.
- With an organization-scoped key, include the destination `projectId` in the creation payload.

The key supplies `organizationId` in either case. Shared catalogs and resources that support Organization scope have different requirements; consult the endpoint's schema.

See [Organizations & Projects](/docs/managing-projects) to choose project boundaries and retrieve a Project ID.

## Create additional keys through the API

Use an existing organization-scoped API key for key-management requests. Your first key comes from the dashboard; creating another key through the API already requires authentication.

To create a project-scoped key, supply its `projectId`:

```http title="Create a project-scoped key"
POST /data_next/core/apiKeys/
Authorization: Bearer {your-org-scoped-key}
Content-Type: application/json

{
  "comment": "Production backend",
  "projectId": "{your-project-id}"
}
```

```json title="Response excerpt"
{
  "id": "{your-api-key-id}",
  "comment": "Production backend",
  "token": "{your-generated-api-key}",
  "projectId": "{your-project-id}",
  "organizationId": "{your-organization-id}"
}
```

Use `token` for authentication and `id` for key-management operations. To create an organization-scoped key, omit `projectId` from the creation payload. Its returned `projectId` is `null`.

Store the token securely. Authorized key-management requests can retrieve it later, and the dashboard lets you reveal or copy an existing key.

## List and revoke keys

These requests require an organization-scoped key:

```http title="List keys"
GET /data_next/core/apiKeys/
Authorization: Bearer {your-org-scoped-key}
```

```http title="Revoke a key"
DELETE /data_next/core/apiKeys/{your-api-key-id}
Authorization: Bearer {your-org-scoped-key}
```

Deleting a key prevents subsequent Reecall API requests using that token. To replace a key, create its replacement, update your backend, verify a request with the new token, then revoke the old key. Revoke an exposed key as soon as possible.

## Troubleshoot access errors

Missing or invalid credentials can return `403` with code `UNAUTHORIZED`. For example:

```json title="Error response"
{
  "message": "Insufficient permissions.",
  "code": "UNAUTHORIZED",
  "status": 403,
  "context": {
    "required": "AUTHENTICATED",
    "current": "EVERYONE"
  }
}
```

| Symptom | Check |
| --- | --- |
| Missing or invalid token | Send `Authorization: Bearer` followed by the token, not the key's `id`. Check that the key has not been revoked. |
| `403` on a management endpoint | Use an organization-scoped key for Project and API key management. |
| Empty results or `404` for an existing resource | Check that the key and resource belong to the same Project or Organization. Resources outside the key's scope may not be visible. |

## Next steps

- [Quickstart](/docs/quickstart) uses a project-scoped key to create your first browser conversation.
- [Organizations & Projects](/docs/managing-projects) explains ownership and project isolation.
- [Variables](/docs/variables) covers storing credentials used by an Assistant's integrations.
