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

# Overview & Auth

> Overview of Onyx APIs

**Nearly every Onyx feature is accessible through the Onyx API.**

Onyx APIs are built on REST principles with JSON request/response formats.
All endpoints require authentication and follow relatively consistent patterns.

Make API requests to:

`https://cloud.onyx.app/api` or `https://your-self-hosted-onyx.com/api`

<Note>
  Onyx follows [SemVer 2.0.0](https://semver.org/). Breaking changes will be indicated by major version increments.
</Note>

<Info>
  This page applies to Onyx **v4.7 and later**, which replaced API key roles with group-based permissions.
  For older versions, see [Overview & Auth before v4.7](/developers/overview_legacy).
</Info>

## Authentication

Every request authenticates with a Bearer token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer <token>" \
  https://cloud.onyx.app/api/me/permissions
```

Onyx has two kinds of token. An **API Key** belongs to a service account. A **Personal Access Token** belongs to you.

### API Keys

API Keys are created by admins from the Admin Panel. Each key exists as a distinct **service account** user in Onyx,
so you can trace activity, keep chat sessions private, and scope resources to a specific key.

A service account has no permissions of its own.
Its access comes from the **groups** you assign to it when you create the key.

| Groups assigned | What the key can do                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| None            | Chat only. It can create sessions and send messages, but it cannot search and cannot reach any admin endpoint.                                 |
| Basic           | Chat, search, projects, and its own agents.                                                                                                    |
| Admin           | Every endpoint, including the ones prefixed with `admin/`.                                                                                     |
| A custom group  | Whatever that group grants. A group with **Manage Connectors & Document Sets**, for example, unlocks the connector and document set endpoints. |

Permissions add together. A key in several groups receives the union of their permissions.

<Warning>
  A key in the **Admin** group has unrestricted access to your Onyx instance.
  Prefer a group that grants only the permissions your integration needs.
</Warning>

<Info>
  Custom groups and configurable group permissions are an Enterprise Edition feature.
</Info>

See [Service Accounts](/admins/user_management/api_keys) for setup instructions.

### Personal Access Tokens

Personal Access Tokens (PATs) let a user authenticate API requests as themselves.

To create a token, go to **Settings** > **Accounts & Access** and click **Create New Token**. Give it a name,
choose an expiration (7 days, 30 days, 365 days, or never), and choose its permissions:

| Permissions    | Behavior                                      |
| -------------- | --------------------------------------------- |
| Full access    | The token inherits all of your permissions.   |
| Limited access | The token is capped to the scopes you select. |

A limited token can pick from these scopes:

| Scope             | Permission        | Allows                                                                                          |
| ----------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| Search — Read     | `read:search`     | Use the search and web search endpoints.                                                        |
| Chat — Read       | `read:chat`       | View chat sessions and messages.                                                                |
| Chat — Write      | `write:chat`      | Create sessions and send messages. Includes Chat — Read.                                        |
| LLM Gateway — Use | `use:llm_gateway` | Call the [LLM Gateway](/developers/guides/llm_gateway) from external tools. Enterprise Edition. |

Scopes only narrow access. A limited token receives the scopes you selected **and** your own permissions,
never more than you can do yourself. A limited token is also rejected on any endpoint outside its scopes,
even one you can reach in the browser.

<Note>
  Creating a token requires the **Create User Access Token** permission, which an admin grants to a group.
  Admins always have it.
</Note>

<Warning>
  Your token is displayed only once at creation. Copy it immediately and store it securely.
</Warning>

You can view, audit, and revoke your tokens at any time from **Settings** > **Accounts & Access**.

## Permissions

Every endpoint page in the [API Reference](/developers/api_reference/chat/get_chat_session)
states the permission it requires. Permissions come from the groups a user or service account belongs to:
`basic` from the Basic group that every user joins, and `admin` from the Admin group, which passes every check.

<Info>
  This permission model applies to Onyx **v4.7 and later**. For how groups, group permissions, and Group Managers work,
  see [Understanding Permissions](/admins/permissions/understanding_permissions).
</Info>

Endpoint pages and `GET /me/permissions` identify a permission by its value.
Each value maps to a permission an admin grants to a group in the Admin Panel:

| Admin Panel                       | Permission                                  |
| --------------------------------- | ------------------------------------------- |
| Manage LLMs                       | `manage:llms`                               |
| Manage Connectors & Document Sets | `manage:connectors`, `manage:document_sets` |
| Manage Actions                    | `manage:actions`                            |
| Manage Groups                     | `manage:user_groups`                        |
| Manage Service Accounts           | `manage:service_account_api_keys`           |
| Manage Slack/Discord Bots         | `manage:bots`                               |
| Create Agents                     | `add:agents`                                |
| Manage Agents                     | `manage:agents`                             |
| View Agent Analytics              | `read:agent_analytics`                      |
| View Query History                | `read:query_history`                        |
| Create User Access Token          | `create:user_api_keys`                      |

A management permission also grants the reads it needs — `manage:connectors` includes `read:connectors` —
so a caller resolves to more permissions than were granted.

### Checking what a token can do

`GET /me/permissions` returns the caller's resolved permissions:

```bash theme={null}
curl -H "Authorization: Bearer <token>" \
  https://cloud.onyx.app/api/me/permissions
```

```json theme={null}
{
  "permissions": ["basic", "manage:connectors", "read:chat", "read:connectors", "..."],
  "is_manager": false,
  "managed_group_ids": []
}
```

A request that fails a permission check returns `403`:

```json theme={null}
{
  "error_code": "INSUFFICIENT_PERMISSIONS",
  "detail": "You do not have the required permissions for this action."
}
```

## API Reference and Playground

In the [API Reference](/developers/api_reference/chat/get_chat_session),
we have curated a subset of useful Onyx API endpoints.
You can experiment with the endpoints on each page or follow one of our [Guides](/developers/guides/chat_new_guide).

You can find all Onyx API endpoints in the built-in OpenAPI explorer:

`https://cloud.onyx.app/api/docs` or `https://your-onyx-domain.com/api/docs`

<Warning>
  The explorer is purely for reference. It is not a fully-featured API client.
  Ignore the tenant\_id parameter and use your API key as a Bearer token.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="lightbulb" href="/developers/core_concepts">
    Learn the fundamental concepts and terminology for working with Onyx APIs
  </Card>

  <Card title="Guide: Send a Chat Message" icon="comment" href="/developers/guides/chat_new_guide">
    Simple example of sending a message programmatically
  </Card>
</CardGroup>