Authentication
Send a workspace API key as a Bearer token with every request.
Authorization: Bearer onym_...API keys
Create keys in Settings → API and MCP; you need the admin role. Onym shows a key once, then stores only its hash. Each key has a name, so you can tell them apart and revoke one without affecting the others.
Keys belong to the workspace: one key reads every domain in it. They work on every plan, and for the MCP server too.
Scopes
| Scope | Can |
|---|---|
read |
Call every GET endpoint |
write |
Everything read can, plus Add prompts |
Use read keys everywhere you can. A read key that leaks can't change anything.
Trying requests in the docs
Code samples show YOUR_API_KEY; replace it with your own key. The Try it panels don't need one: they run read-only requests against the demo workspace, or against your own data when you're signed in, and no key is ever shown on the page.
OAuth tokens
AI assistants that connect to the MCP server with OAuth get access tokens starting onym_at_. They work on the REST API too, last an hour, and are refreshed by the client.
Keeping keys safe
Never put an API key in front-end code, a mobile app or a public repository. Call the API from your server.
- Use a separate key per integration, named after it.
- Revoke keys when someone with access leaves.
- The CSV dataset endpoint accepts
?key=for spreadsheets; use a dedicated read key there, since anyone with the sheet can see it.
Errors
| Status | code |
Meaning |
|---|---|---|
| 401 | missing_api_key |
No Authorization: Bearer header |
| 401 | invalid_api_key |
The key is unknown or revoked |
| 401 | token_expired |
An OAuth access token expired; refresh it |
| 403 | read_only_key |
A read key was used to write |