mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-16 13:05:14 +03:00
docs(console): explain API keys and scoped permissions (#57386)
This commit is contained in:
committed by
GitHub
Unverified
parent
d8148796dc
commit
930c0c8b6a
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user