API Keys
API keys give trusted backend services, CI jobs, and internal automations REST API access to one workspace. A key belongs to the workspace, not to a signed-in user.
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 harnesses |
For access a person approves from their own account, use OAuth Apps.
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"
With an API key, workspaceId=current resolves to the workspace that owns the key, so you do not need to hardcode a workspace ID.
The same key works with the JavaScript SDK from a Node service, or the Swift SDK from a trusted server-side Swift process. Never embed an access token or API key in a mobile app; treat anything shipped in an app as public. For anonymous features such as “Report issue”, have the app call your backend and create the bug there with the workspace key.
import { Configuration, TasksApi } from '@onehorizon/sdk-js' const config = new Configuration({ accessToken: process.env.ONE_API_KEY })const tasks = new TasksApi(config)
import OneHorizonimport Foundation // Server-side Swift only. Never embed this key in an iOS app. See the Swift SDK guide.let config = OneHorizonAPIConfiguration.sharedconfig.customHeaders["Authorization"] = "Bearer \(ProcessInfo.processInfo.environment["ONE_API_KEY"] ?? "")"
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"}'
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, public repositories, logs, and screenshots.
Do not use API keys for agent execution. Agent profile, harness, 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.