API keys and tokens

Personal API keys for scripts, deploy machines, and agents — and how the CLI picks its credential.

Markdown

All pages

Everything that talks to oak.space — the CLI, the HTTP API, CI jobs, agents — authenticates with a bearer token:

Authorization: Bearer oak_...

There are three kinds of token.

TokenComes fromLifetimeUse it for
Login sessionoak login90 daysYou, at your own terminal.
Personal API keyYou create itUntil revokedScripts and tools acting as you.
Agent keyAn org admin creates it for one of the organization's agentsUntil revokedBots, deploy machines, and agents with their own identity.

Personal API keys#

Create one under Settings → API keys on oak.space, or over the API:

curl -X POST https://oak.space/api/api-keys \
  -H "Authorization: Bearer $OAK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "release script", "scope": "read", "repo": "acme/web"}'
FieldValue
name1–100 characters, for your own reference.
scopefull (default) or read — a read key can only make read requests.
repoOptional owner/name. The key then works only for that one repo.
expires_inOptional lifetime in seconds, from one minute to 366 days. Omitted, the key lasts until you revoke it.
org, groupsMake it a key for an agent.

The full key is shown once, when it's created. After that only its first characters are displayed, so store it somewhere safe. List your keys with GET /api/api-keys and revoke one with DELETE /api/api-keys/{id}.

A personal key acts as you, with your access — a repo-scoped or read-only key can only do less, never more.

Keys for agents#

A personal key acts as you. If you're on groups that read a private directory, or you own the organization, so does anything holding your key. A key for an agent gives away less:

curl -X POST https://oak.space/api/api-keys \
  -H "Authorization: Bearer $OAK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "web agent", "org": "acme", "groups": ["web"], "expires_in": 28800}'

Or open For an agent under Settings → API keys.

FieldValue
orgThe organization the key works in. It can't reach any other, or your account.
groupsGroups of that organization you are on. Leave it out for no group. An organization owner or admin can name any group.

Inside a repo, boundaries treat the key as a member of those groups and the groups above them, and as nobody else:

GET /api/whoami with such a key answers with a grant block (org, groups), so an agent can tell what it is.

Two things to know:

Organization agents#

An organization agent is a non-human identity owned by an organization — a deploy bot, a build machine, a coding agent that runs unattended. Its actions show up under its own name in the audit log.

It reaches what the groups it's on reach, the same way a person does. A new agent is on no group, so it reaches only the organization's public repos. Put it on a group, and it reads or writes the repos that group was given, and path rules judge it as a member of that group. It doesn't borrow anything from whoever created it or issued its keys: an owner's agent doesn't get the owner's access.

Organization owners and admins create them and issue their keys under the organization's Settings → Agents, or over the API. Whoever manages a group adds agents to it from a repo's Settings → Access, or over the API. An agent made from a repo's Settings → Access (or created with "repo": "<name>") is confined to that repo: it reaches that repo and nothing else, whatever its groups reach, and deleting the repo deletes it.

# Create the agent
curl -X POST https://oak.space/api/orgs/acme/agents \
  -H "Authorization: Bearer $OAK_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "nightly-agent", "display_name": "Nightly refactor agent"}'

# Put it on the web group, so it reaches what web reaches
curl -X PUT https://oak.space/api/orgs/acme/groups/web/agents/nightly-agent \
  -H "Authorization: Bearer $OAK_TOKEN"

# Give it a key that can push branches
curl -X POST https://oak.space/api/orgs/acme/agents/nightly-agent/keys \
  -H "Authorization: Bearer $OAK_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "prod", "scopes": "read,write"}'
ScopeAllows
readEvery read request an agent makes: clone, pull, list, view.
writePush branches, describe, close, reopen and rename them, move the marks its groups own and file reports on commits, in repos its groups can write.
releaseMove a protected mark (one whose grants carry a fixed identity a deploy box checks). No other scope implies it.

Scopes are required on an organization agent's keys. They do an agent's work, like a key for an agent: merging, approving, creating repos, and anything under settings take a person's credential, so an organization agent's key can't carry merge, review or admin. A key only works inside its own organization: the repos its groups reach (/api/{org}/{repo}/...), /api/repos (which lists those repos), /api/whoami and /api/capabilities. A repo its groups weren't given answers 404, and anything else outside its reach answers 403 saying why. GET /api/whoami answers with a grant block listing its groups.

Organization agents and their keys can only be managed from a signed-in session, never with an API key, so a key can't mint itself a stronger one.

Disable an agent (PATCH /api/orgs/{slug}/agents/{name} with {"disabled": true}) to stop all its keys at once, or delete it. Revoke one key with DELETE …/agents/{name}/keys/{key_id}. The older /api/orgs/{slug}/service-accounts paths still work.

For coding agents, a read,write organization agent key can clone, push its branches, and move the marks its groups own, but can't merge to main: merging stays a human decision. If its groups can't read every directory, it's a restricted reader.

Using a key with the CLI#

export OAK_API_KEY=oak_...
oak clone acme/web
oak auth status       # confirms which credential is in use and who it resolves to

The CLI picks its credential in this order:

  1. OAK_API_KEY, if set.
  2. A key stored in the checkout itself (oak clone saves one, bound to the server it came from).
  3. Your oak login session for that server, from ~/.config/oak/credentials.

If a push or pull unexpectedly says a repo you know exists isn't found, a stale key from step 2 is the usual suspect — oak auth status shows which source is winning.

Using a key with the API#

curl https://oak.space/api/repos -H "Authorization: Bearer $OAK_API_KEY"

See the HTTP API reference.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].