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.
| Token | Comes from | Lifetime | Use it for |
|---|---|---|---|
| Login session | oak login | 90 days | You, at your own terminal. |
| Personal API key | You create it | Until revoked | Scripts and tools acting as you. |
| Agent key | An org admin creates it for one of the organization's agents | Until revoked | Bots, 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"}'
| Field | Value |
|---|---|
name | 1–100 characters, for your own reference. |
scope | full (default) or read — a read key can only make read requests. |
repo | Optional owner/name. The key then works only for that one repo. |
expires_in | Optional lifetime in seconds, from one minute to 366 days. Omitted, the key lasts until you revoke it. |
org, groups | Make 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.
| Field | Value |
|---|---|
org | The organization the key works in. It can't reach any other, or your account. |
groups | Groups 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:
- It isn't you. A boundary that lists
@youdoesn't reach it, and it never has an owner's or admin's full access, whoever made it. - It follows your membership. Leave a group and your keys lose it on their next request.
- It does an agent's work: clone, pull, push branches, describe and close them, move the marks its groups own and file reports on commits. Merging, approving, and anything under settings take your own credential.
- If its groups can't read every directory, it's a restricted reader like any other. It gets a checkout without those directories and doesn't see branches that touch them.
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:
- Groups take access away only where a boundary lists readers or writers. A key on
webstill reads every directory that's open to all of the repo's readers. - A key protects you only where the agent can't reach your login.
oak loginstores a session in~/.config/oak/credentials, and a session can make new keys. Give an agent this key in a container, on a remote machine, or in a sandbox without your home directory.
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"}'
| Scope | Allows |
|---|---|
read | Every read request an agent makes: clone, pull, list, view. |
write | Push branches, describe, close, reopen and rename them, move the marks its groups own and file reports on commits, in repos its groups can write. |
release | Move 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,writeorganization agent key can clone, push its branches, and move the marks its groups own, but can't merge tomain: 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:
OAK_API_KEY, if set.- A key stored in the checkout itself (
oak clonesaves one, bound to the server it came from). - Your
oak loginsession 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.