API Keys
Use API keys when a trusted backend service, CI job, or internal automation needs 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.
When to use API keys
| Use API keys for | Use something else 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 |
Use OAuth Apps when a person needs to approve access 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"}'
Use the CLI page for terminal setup and workspace selection. API key list, create, and revoke operations are REST API operations; exact requests live 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 error shapes and retry behavior, use the REST API page and the API reference.