mirror of
https://github.com/onyx-dot-app/documentation.git
synced 2026-07-25 13:46:14 -04:00
Yuhong Sun
113 lines
3.7 KiB
Plaintext
113 lines
3.7 KiB
Plaintext
---
|
|
title: "Overview & Auth"
|
|
description: "Overview of Onyx APIs"
|
|
icon: "code"
|
|
---
|
|
|
|
**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>
|
|
|
|
## Authentication
|
|
|
|
### API Keys
|
|
|
|
API Keys are created by admins from the Admin Panel. Each key exists as a distinct user in Onyx,
|
|
meaning you can trace activity, keep chat sessions private, and scope resources to a specific key.
|
|
|
|
There are three types:
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Admin API Keys" icon="shield-check">
|
|
Can access all endpoints, including those pre-fixed with `admin/`.
|
|
|
|
**Use cases:**
|
|
- Full system administration
|
|
- User management operations
|
|
- Data management and analytics
|
|
- Complete access to all Onyx features
|
|
|
|
**⚠️ Use with caution:** Admin keys have unrestricted access to your Onyx instance.
|
|
</Accordion>
|
|
|
|
<Accordion title="Basic API Keys" icon="key">
|
|
Can access the non-admin endpoints like Search, Chat, Agents, and Actions.
|
|
|
|
**Use cases:**
|
|
- Building chat applications
|
|
- Implementing search functionality
|
|
- Creating and managing agents
|
|
- Running actions and workflows
|
|
|
|
**✅ Recommended:** Most users should use Basic API Keys for application development.
|
|
</Accordion>
|
|
|
|
<Accordion title="Limited API Keys" icon="lock">
|
|
Read-only Agent access. Can post messages to Chat endpoints, but cannot read chat history.
|
|
|
|
**Use cases:**
|
|
- Highly restricted environments
|
|
- Specific use cases requiring minimal permissions
|
|
- Testing with limited scope
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
See [API Keys](/admins/user_management/api_keys) for setup instructions.
|
|
|
|
### Personal Access Tokens
|
|
|
|
Personal Access Tokens (PATs) let any user authenticate API requests as themselves. Unlike API Keys,
|
|
PATs inherit your own role and permissions, so they can access exactly what you can.
|
|
|
|
To create a token, go to **Settings** > **Accounts & Access** and click **Create New Token**.
|
|
Give it a name and choose an expiration (7 days, 30 days, 365 days, or never).
|
|
|
|
<Warning>
|
|
Your token is displayed only once at creation. Copy it immediately and store it securely.
|
|
</Warning>
|
|
|
|
Use the token as a Bearer token in the `Authorization` header:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer onyx_pat_..." \
|
|
https://cloud.onyx.app/api/chat/get-user-chat-sessions
|
|
```
|
|
|
|
You can view, audit, and revoke your tokens at any time from **Settings** > **Accounts & Access**.
|
|
|
|
## 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>
|