API Keys
API keys give trusted backend services, CI jobs, and internal automations REST API access to one workspace.
API keys are workspace-scoped. They are not tied to one signed-in user, so they are best for server-side systems you control.
Where API keys fit
| API keys fit | Choose another path for |
|---|---|
| Backend services that read or update workspace data | Browser or mobile clients |
| CI jobs and deployment automation | Log in with One Horizon or Connect One Horizon |
| Internal sync jobs and reporting scripts | MCP, CLI, or other user-approved tools |
| Trusted integrations that act for one workspace | Local or cloud agent workers |
OAuth Apps are for access a person approves from their own account.
Create a key
Workspace owners and admins create keys from Settings > Developer > API Keys.
- Choose Add key.
- Add a description that names the service and environment.
- Create the key.
- Copy the secret immediately.
- Store it in a secrets manager or environment variable such as
ONE_API_KEY.
The secret is shown once. If you lose it, revoke the key and create a replacement.
Create one key per integration and environment. For example, keep ci-production, ci-staging, and n8n-production separate so each key can be revoked without breaking unrelated systems.
Use a key
Send the key as a bearer token on every REST API request:
curl "https://onehorizon.ai/api/v1/workspaces/current/tasks?all=true" \ -H "Authorization: Bearer $ONE_API_KEY"
Use workspaceId=current for workspace routes. With an API key, current resolves to the workspace that owns the key, so you do not need to hardcode a workspace ID.
The same key can be used with the JavaScript SDK:
import { Configuration, TasksApi } from '@onehorizon/sdk-js' const config = new Configuration({ accessToken: process.env.ONE_API_KEY })const tasks = new TasksApi(config)
Create from a terminal
API key management endpoints require an OAuth token from a workspace owner or admin. An API key cannot list, create, or revoke API keys.
curl -X POST "https://onehorizon.ai/api/v1/workspaces/current/api-keys" \ -H "Authorization: Bearer $ONE_OAUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{"description":"ci-production"}'
The CLI page covers terminal setup and workspace selection. For key rotation from your own script, use the API key routes in the API reference.
Limits and access
A workspace can have up to 20 active API keys. All API key requests in the same workspace share the same workspace rate limit.
API keys have workspace-level read and write access. Keep them out of browser code, mobile apps, public repositories, logs, and screenshots.
Do not use API keys for agent execution. Agent profile, worker, session, claim, and activity endpoints require OAuth user tokens so execution remains tied to a user-approved path.
Rotate or revoke a key
Create a replacement key, update the external service, confirm traffic has moved, then revoke the old key. Revocation is immediate and requests using the revoked key fail.
For failed requests, start with the REST API page.