API keys and access | Ara Documentation

Every API request uses an ara_ key as a bearer token. Create keys in Settings → Ara API.

$ curl https://api.ara.so/v3/self \
>   -H "Authorization: Bearer ara_..."

Treat keys like passwords. They are shown once. Store them in a secret manager, never in source control.

Principals

Most API keys belong to service users. A service user is a machine principal for CI, scripts, and automations.

Human users have roles in the organization. Service users have scopes on their keys.

Scope	Grants
`run`	Open, steer, tag, cancel, and schedule agent work.
`sessions:read`	Read sessions, messages, tags, insights, and attachments.
`repos:read`, `repos:write`	Read repositories and manage indexing.
`blueprints:read`, `blueprints:write`	Read and manage environment setup.
`knowledge:read`	Legacy compatibility scope for reading automations.
`memory:read`, `memory:write`	Read and manage editable notes for connected repositories. Generated native memory stays read-only.
`secrets:read`, `secrets:write`	List secret names, set secrets, and delete secrets.
`plugins:read`, `plugins:write`	Read and manage MCP servers and git plugins.
`attachments:read`, `attachments:write`	Download and upload attachments.
`reviews:read`, `reviews:write`	Read and trigger pull request or merge request reviews.
`guardrails:read`, `guardrails:write`	Read and manage repository guardrails.
`analytics:read`	Read metrics, consumption, queue status, and audit logs.
`org:read`, `org:write`	Read and manage orgs, members, roles, and service users.
`ip:read`, `ip:write`	Read and manage the IP access list.

Use the narrowest scopes that work. There is no secret-reveal scope. Secret values are write-only.

Most resources live under /v3/organizations/{org_id}/.... Resolve the id once and cache it.

GET /v3/self returns the service user and org.

1 {
2   "principal_type": "service_user",
3   "service_user_id": "key_3f9a",
4   "service_user_name": "ci-bot",
5   "org_id": "org_8c2d1e"
6 }

Rotate a service user’s key when it may have left your control. The new key is shown once. The old value cannot be recovered.

Status	Meaning
`401`	Missing, invalid, or expired key
`403`	Key lacks the scope, or the organization is not accessible
`429`	Rate limited. Honor the `Retry-After` header