docs(console): explain API keys and scoped permissions (#57386)

This commit is contained in:
Victor Navarro
2026-10-20 14:06:18 +02:00
committed by GitHub
Unverified
parent d8148796dc
commit 930c0c8b6a
3 changed files with 115 additions and 149 deletions
@@ -7,8 +7,9 @@ Read effective monthly budgets for every workspace member and manage each member
## Quick start
Create a [service account](/console/api#service-accounts) API key with **All** permissions in the [Console](https://opencode.ai/console).
Inference-only keys cannot access budget data or change limits.
Create a [service account](/console/api#service-accounts) API key in the [Console](https://opencode.ai/console) with
**All** [permissions](/console/api#permissions), or **Restricted** with **Budgets** set to **Write**. **Budgets › Read**
is enough to list budgets.
```bash
export CONSOLE_URL="https://opencode.ai/console"
@@ -1,17 +1,14 @@
---
title: "API Overview"
description: "Authenticate with the OpenCode Console API using personal API keys, service account keys, or user tokens."
description: "Authenticate with the OpenCode Console API using personal API keys or service account keys, and scope what each key can do."
---
The Console API lets integrations read workspace configuration and manage budgets. Paths are relative
to the Console base URL.
The Console API lets your scripts and integrations call models and manage budgets. Every request authenticates with
an API key.
```bash
export CONSOLE_URL="https://opencode.ai/console"
export SERVICE_API_KEY="oc_sk_..."
curl --fail-with-body "${CONSOLE_URL}/api/v2/config" \
--header "Authorization: Bearer ${SERVICE_API_KEY}"
curl --fail-with-body "https://opencode.ai/console/api/v1/budgets/members" \
--header "Authorization: Bearer oc_sk_..."
```
| API | Endpoints |
@@ -19,171 +16,139 @@ curl --fail-with-body "${CONSOLE_URL}/api/v2/config" \
| [Inference](/console/api/inference) | `https://opencode.ai/inference/...` |
| [Providers](/console/api/providers) | `https://opencode.ai/inference/custom/...` |
| [Budgets](/console/api/budgets) | `/api/v1/budgets/members` |
| [Config](#workspace-config) | `GET /api/v2/config` |
## Personal API keys
## API keys
Every member can create personal API keys. A personal key acts as you, and its usage counts toward your
[member budget](/console/budgets#member-budgets). Use one for your own scripts and [harnesses](/console/harnesses).
1. Open **Account** from the account menu and find **Personal API keys**.
2. Click **Add API key**.
3. Choose the **Workspace**, a **Key name**, and an optional **Expiration**, then click **Create**.
4. Copy the key. It is shown only once.
Send it as a bearer token, like a service account key. Each key works in the workspace chosen when it was created.
Both workspace members and service accounts can have API keys. Send a key as a bearer token.
```text
Authorization: Bearer oc_sk_...
```
Members' keys can list and call models. Owners and admins can also grant Console API permissions, up to their own role.
A key can never create other keys.
| | Personal API key | Service account key |
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------------------ |
| Created by | Any member, for themselves | Owners and admins |
| Created in | **Account › Personal API keys** | **Settings › Service accounts** |
| Acts as | The member who created it | The service account |
| Usage counted to | The member's [budget](/console/budgets#member-budgets) | The service account's [budget](/console/budgets#service-account-budgets) |
| Best for | Your own scripts and [harnesses](/console/harnesses) | CI, shared machines, and integrations |
Revoke a key from **Personal API keys** on the **Account** page. Owners and admins can see and revoke a member's keys
from the member's page under **Members**. Leaving or being removed from a workspace revokes your keys in it.
- Each key works in one workspace, chosen when it is created. No workspace header is needed.
- The full key is shown only once, right after you create it. Afterward Console shows only its prefix.
- **Expiration** is optional: **Never**, **1 day**, **7 days**, **30 days**, or **Custom** (1 to 365 days). An expired
key can't be renewed, so create a new one.
## Service accounts
## Personal API keys
Integrations authenticate with a service account: a non-human member of the workspace with its own API keys, usage,
and [budget](/console/budgets#service-account-budgets). Owners and admins manage them from **Keys**.
A personal key acts as you. Your role, [budgets](/console/budgets#member-budgets), and model rules apply to it.
1. Open **Keys** and click **Add Service Account**, then name it, for example `CI Pipeline`.
2. Open the service account and click **Add API Key**.
3. Choose a **Key name**, **Permissions**, and an optional **Expiry date**, then click **Create key**.
4. Copy the key. It is shown only once.
1. Open **Account** from the account menu and find **Personal API keys**.
2. Click **Add API key**.
3. Choose the **Workspace**, a **Key name**, and an optional **Expiration**. Owners and admins also choose
**Permissions**.
4. Click **Create** and copy the key.
```text
oc_sk_1a2b3c4d5e6f_...
```
Send the key as a bearer token. It is bound to one workspace, so no workspace header is needed.
The key follows your current access to the workspace. If your role changes, so does what the key can do. If the
workspace enforces [SSO](/console/sso#sso-enforcement), the key works only while you have an active SSO session, unless
you are an owner.
## Service accounts
A service account is a non-human member of the workspace with its own API keys, usage, and
[budget](/console/budgets#service-account-budgets). Use one for automation, so usage isn't tied to a person. Owners and
admins manage them.
1. Open **Settings › Service accounts** and click **Add Service Account**, then name it, for example `CI Pipeline`.
2. Open the service account and click **Add API Key**.
3. Choose a **Key name**, an optional **Expiration**, and **Permissions**, then click **Create**.
4. Copy the key.
```bash
export SERVICE_API_KEY="oc_sk_..."
```
Owners and admins can rename a service account key or change its permissions later with **Edit…** in the key's actions
menu.
## Permissions
Each key has a permission level, chosen under **Permissions** when you create it.
| Permissions | Allows |
| -------------- | ------------------------------------------------------------------------------------ |
| **All** | Everything the member or service account can do, except **This account's API keys**. |
| **Restricted** | Only the resources you choose. |
| **Read only** | Read access to every resource. The key can list models but not call them. |
A key never does more than whoever it acts as. A personal key is capped by the member's current role, and a service
account key by what [service accounts can do](#limitations).
### Restricted keys
Set each resource to **None**, **Read**, or **Write**. **Write** includes **Read**.
| Resource | Levels |
| --------------------------- | --------------------- |
| **Models** | **Read**, **Request** |
| **Usage** | **Read** |
| **Budgets** | **Read**, **Write** |
| **Members** | **Read**, **Write** |
| **Providers** | **Read**, **Write** |
| **Billing** | **Read**, **Write** |
| **Workspace settings** | **Read**, **Write** |
| **SSO** | **Read** |
| **Service accounts** | **Read** |
| **This account's API keys** | **Write** |
**Models › Read** lists models, and **Models › Request** also calls them through the [Inference](/console/api/inference)
and [Providers](/console/api/providers) APIs. For example, a key for a budget integration only needs:
```text
Authorization: Bearer oc_sk_...
Permissions: Restricted
Budgets: Write
```
### Permissions
Keys created as **Inference only** before scoped permissions show as **Restricted** with **Models** set to **Request**.
| Permission | Allows |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| Inference only | [Inference](/console/api/inference) and [Providers](/console/api/providers) requests, and `GET /api/v2/config`. |
| All | Everything above, plus the Console API with admin access, except managing models. |
### Who can grant what
Some actions always require a person signed in to the Console, even with an **All** key: inviting members, changing
roles, removing members, and creating or revoking keys.
- **Members** can only create personal keys that list and call models. Console shows "This key can list and call
models as you." instead of permission choices.
- **Owners and admins** can give their personal keys **All**, **Restricted**, or **Read only**, up to their own role.
The default is **Restricted** with **Models** set to **Request**. If they are later demoted, their keys shrink to
match.
- **Service account keys** default to **All**. Owners and admins choose their permissions.
### Revoke keys
### Limitations
Open the service account and revoke a key from **API Keys**. Removing the service account revokes all its keys.
Automations using a revoked or expired key get HTTP `401` immediately.
Some actions always need a person signed in to the Console, and creating keys with a key is tightly limited.
## User tokens
- No API key can change SSO settings or delete the workspace.
- Service account keys can't invite members, change roles, remove members, manage billing, change workspace settings,
manage models, or create or remove service accounts, even with **All**.
- **This account's API keys** is only available on service account keys, and **All** doesn't include it. A key with it
can create and revoke keys for its own service account only. New keys must be **Restricted**, stay within the
creating key's permissions, and can't include **This account's API keys**.
- Personal keys can never get **This account's API keys**, and no API key can create or revoke personal API keys.
User tokens act as a signed-in person with their workspace role. Send the token with an `x-org-id` header naming the
workspace.
Requests outside a key's permissions return HTTP `403`.
```bash
curl --fail-with-body "${CONSOLE_URL}/api/v2/config" \
--header "Authorization: Bearer ${USER_TOKEN}" \
--header "x-org-id: org_..."
```
## Revocation
Tokens from the [device flow](#device-flow) are bound to the workspace chosen during sign-in and do not need the
header. A different `x-org-id` returns `403`.
| Key | Who can revoke it | Where |
| ------------------- | ---------------------- | --------------------------------------------------------------------------------- |
| Personal API key | The member who owns it | **Account › Personal API keys**, then **Revoke** |
| Personal API key | Owners and admins | The member's page in **Settings › Members**, under **API Keys** |
| Service account key | Owners and admins | The service account's page in **Settings › Service accounts**, under **API Keys** |
## Device flow
Keys are also revoked automatically:
OpenCode signs in with the OAuth device authorization grant (RFC 8628). Other CLIs can use the same flow.
- Leaving or being removed from a workspace, or being deprovisioned through [SCIM](/console/scim), revokes every key
that person created in it, including service account keys. Other keys on the same service account keep working.
- Removing a service account revokes all its keys.
1. Request a device code. Send `supports_org_scope=true` to bind the token to a workspace.
```bash
curl --fail-with-body "${CONSOLE_URL}/auth/device/code" \
--data "client_id=my-cli" \
--data "supports_org_scope=true"
```
The response includes `device_code`, `user_code`, `verification_uri_complete`, `expires_in` (600 seconds), and
`interval` (5 seconds).
2. Open `verification_uri_complete` in a browser. It is a path such as `/console/device?user_code=...`, relative to
`https://opencode.ai`. The person signs in, picks a workspace, and approves.
3. Poll for the token every `interval` seconds with the same `client_id`.
```bash
curl --fail-with-body "${CONSOLE_URL}/auth/device/token" \
--data "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
--data "device_code=..." \
--data "client_id=my-cli"
```
Until approval the response is `400` with `authorization_pending`. On success it returns `access_token`,
`refresh_token`, `expires_in`, and `org_id`.
4. Refresh before the access token expires. The workspace binding is preserved.
```bash
curl --fail-with-body "${CONSOLE_URL}/auth/device/token" \
--data "grant_type=refresh_token" \
--data "refresh_token=..." \
--data "client_id=my-cli"
```
Each refresh token can be used once. Reusing an old refresh token revokes the whole session.
## Workspace config
`GET /api/v2/config` returns the providers and models available to the workspace in the OpenCode V2
[config](/config) format. OpenCode loads it after `/connect`.
```bash
curl --fail-with-body "${CONSOLE_URL}/api/v2/config" \
--header "Authorization: Bearer ${SERVICE_API_KEY}"
```
```json
{
"providers": {
"opencode": {
"name": "OpenCode",
"env": ["OPENCODE_CONSOLE_TOKEN"],
"package": "aisdk:@ai-sdk/openai-compatible",
"settings": {
"baseURL": "https://opencode.ai/inference/openai/v1",
"apiKey": "{env:OPENCODE_CONSOLE_TOKEN}"
},
"headers": { "x-opencode-org-id": "org_..." },
"models": {
"kimi-k2.6": { "name": "Kimi K2.6" }
}
}
}
}
```
| Field | Description |
| ----------------------- | -------------------------------------------------------------------------------- |
| `providers` | Console, Go, and connected providers, each with its gateway settings and models. |
| `websearch` | Hosted [web search](/console/websearch), for members when enabled. |
| `mcp` | The Console MCP server, for members. |
| `policies` | Workspace [policy](/policies#console) statements. |
| `experimental.policies` | Deprecated name for `policies`, still accepted. |
Every key permission level and member role can read the config.
## Errors
Errors return JSON with a `_tag` naming the error.
```json
{ "_tag": "Forbidden" }
```
| Status | Meaning |
| ------ | ---------------------------------------------------------------------------------------- |
| `400` | `OrgRequired`: a user token was sent without `x-org-id`. |
| `401` | Missing, invalid, expired, or revoked credential. |
| `403` | Wrong workspace, missing permission, or an **Inference only** key on a Console endpoint. |
| `404` | The workspace does not exist or was deleted. |
Revoked and expired keys stop working immediately and return HTTP `401`.
@@ -58,8 +58,8 @@ You can only grant roles up to your own, and the workspace always keeps at least
Access is revoked immediately, and you can invite them again later. Their past usage stays in the workspace's reports.
Service accounts and their API keys belong to the workspace, so removing the member who created them does not revoke
them. Revoke keys from **Keys** if needed. See [Service accounts](/console/api#service-accounts).
Removing a member also revokes the API keys they created in the workspace, including service account keys. Service
accounts themselves stay, and keys other people created keep working. See [Revocation](/console/api#revocation).
## Member details