> ## Documentation Index
> Fetch the complete documentation index at: https://danswer-docs-versions-opensearch-example.mintlify.site/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>


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