API Reference: Authentication, Errors & Endpoints

The OneCLI API gives you programmatic access to everything behind the gateway: workspaces, agents and what each agent may use, secrets, app connections, organization policy, and, for hosted agents, their conversations, schedules, memory, skills, and Slack channels. Per-agent access is written through the Grants endpoints (attach a connection or secret to an agent, optionally with per-tool allow and approval lists and resource scoping; see Agent access). Organization-wide guardrails live under /org/policy; the workspace /policy endpoints are read-only reflections of the enforced result. Every endpoint page states which editions it is available on.

Base URL

https://api.onecli.sh/v1

http://localhost:10254/v1

The approvals long-poll endpoints are served by the gateway instead (https://gw.onecli.sh on Cloud, http://localhost:10255 self-hosted). GET /gateway-url returns the right origin for any deployment. SCIM has its own base path, /scim/v2, and its own tokens.

Authentication

All API endpoints require authentication unless their page says otherwise. Include your API key as a Bearer token in the Authorization header:

curl https://api.onecli.sh/v1/agents \
  -H "Authorization: Bearer oc_your_api_key_here"

Workspace keys

Workspace API keys start with oc_ and are scoped to a single workspace. A workspace key always operates on its own workspace. Read yours from the dashboard, or with GET /user/api-key.

Organization keys

Organization API keys start with oc_org_ and operate across workspaces. For workspace-scoped endpoints, include the X-Workspace-Id header to name the workspace (without it, workspace endpoints return 401):

curl https://api.onecli.sh/v1/agents \
  -H "Authorization: Bearer oc_org_your_key_here" \
  -H "X-Workspace-Id: ws_abc123"

Organization endpoints (/org/...) need no workspace header. Where roles are enforced (Cloud and Enterprise) they require the admin or owner role; the Community edition runs a flat team where every member passes.

X-Workspace-Id replaced X-Project-Id, and /v1/workspaces replaced /v1/projects. The old header, the ?_project query bridge, and the /v1/projects path alias still work for a deprecation window and answer with a Deprecation: true header. Migrate to the new names.

Dashboard sessions

The web dashboard calls the same API with its own session: a bearer JWT on Cloud, the session cookie on self-hosted deployments. A few endpoints are session-only (deleting your account, accepting an invitation, claiming a provisioned account), because they act for the person rather than a workspace or organization. API keys are refused there.

Errors

The API returns standard HTTP status codes. Validation errors return a flat error string; authentication and service errors use an envelope with message and type:

{
  "error": "Label is required"
}

{
  "error": {
    "message": "Invalid API key or token.",
    "type": "authentication_error"
  }
}

Status	Meaning
`400`	Validation error or bad request
`401`	Missing or invalid authentication, or a missing `X-Workspace-Id`
`403`	Insufficient permissions, a plan or quota limit (Cloud), or an Enterprise feature on a Community deployment
`404`	Resource not found
`409`	Conflict (duplicate identifier, a turn already in flight, a stale reorder)
`410`	Endpoint retired; the message names the replacement
`413`	Upload too large
`422`	The body parsed but violates a validation law
`429`	Rate limited

See Errors for the full reference, including the retired-endpoint inventory. Errors on an agent’s proxied traffic (including the 409 account-selection protocol) are a separate surface: Gateway errors and Multiple accounts.

Rate limits

The gateway enforces rate limits on proxied requests via policy rules. A handful of management endpoints are throttled too (the SSO lookup, SSO connection tests, and SCIM), and say so on their page.

​Base URL

​Authentication

​Workspace keys

​Organization keys

​Dashboard sessions

​Errors

​Rate limits

Base URL

Authentication

Workspace keys

Organization keys

Dashboard sessions

Errors

Rate limits