docs(console): document personal API keys (#57188)

2026-11-10 23:30:52 +03:00 · 2026-10-19 21:54:44 +02:00
parent 92242b5539
commit c193810f65
8 changed files with 42 additions and 13 deletions
@@ -1,6 +1,6 @@
 ---
 title: "API Overview"
-description: "Authenticate with the OpenCode Console API using service account keys or user tokens."
+description: "Authenticate with the OpenCode Console API using personal API keys, service account keys, or user tokens."
 ---

 The Console API lets integrations read workspace configuration and manage budgets. Paths are relative
@@ -21,6 +21,28 @@ curl --fail-with-body "${CONSOLE_URL}/api/v2/config" \
 | [Budgets](/console/api/budgets)     | `/api/v1/budgets/members`                  |
 | [Config](#workspace-config)         | `GET /api/v2/config`                       |

+## Personal 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.
+
+```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.
+
+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.
+
 ## Service accounts

 Integrations authenticate with a service account: a non-human member of the workspace with its own API keys, usage,
@@ -18,7 +18,7 @@ curl -X POST "https://opencode.ai/inference/openai/v1/chat/completions" \

 ## Authentication

-Replace `<token>` with a [service account key](/console/api#service-accounts) created in the [Console](https://opencode.ai/console). Paid models
+Replace `<token>` with a [personal API key](/console/api#personal-api-keys) or a [service account key](/console/api#service-accounts) created in the [Console](https://opencode.ai/console). Paid models
 require the header; free chat models can be called without it.

 ```text
@@ -12,7 +12,7 @@ export ANTHROPIC_AUTH_TOKEN="oc_sk_..."
 claude --model claude-sonnet-5-5
 ```

-Create the key under **Keys** in the [Console](https://opencode.ai/console). See [Get an API key](/console/harnesses#get-an-api-key).
+Replace `oc_sk_...` with a [personal API key](/console/harnesses#get-an-api-key).

 ## Configure

@@ -21,8 +21,8 @@ env_key = "OPENCODE_API_KEY"
 wire_api = "responses"
 ```

-Codex appends `/responses` to the base URL and reads the key from `env_key`. Create the key under **Keys** in the
-[Console](https://opencode.ai/console), then export it.
+Codex appends `/responses` to the base URL and reads the key from `env_key`. Create a
+[personal API key](/console/harnesses#get-an-api-key), then export it.

 ```bash
 export OPENCODE_API_KEY="oc_sk_..."
@@ -19,7 +19,7 @@ Run the model setup and select **OpenCode Zen** for pay-as-you-go or **OpenCode
 hermes model
 ```

-Paste a key created under **Keys** in the [Console](https://opencode.ai/console), then choose a model. Hermes saves the
+Paste a [personal API key](/console/harnesses#get-an-api-key), then choose a model. Hermes saves the
 key to `~/.hermes/.env` and the selection to `~/.hermes/config.yaml`.

 ```yaml title="~/.hermes/config.yaml"
@@ -16,14 +16,23 @@ is billed to your workspace like any other request.

 ## Get an API key

-Harnesses authenticate with a [service account](/console/api#service-accounts) key. Open **Keys** in the
-[Console](https://opencode.ai/console), add a service account, and create a key with **Inference only** permission.
+Harnesses authenticate with a Console API key. The quickest option is a
+[personal API key](/console/api#personal-api-keys), which calls models as you.
+
+1. Open **Account** from the account menu in the [Console](https://opencode.ai/console).
+2. Under **Personal API keys**, click **Add API key**.
+3. Choose the workspace, name the key, and click **Create**.
+4. Copy the key. It is shown only once.

 ```text
 oc_sk_1a2b3c4d5e6f_...
 ```

-Use a key from a workspace with credits for pay-as-you-go, or from a workspace subscribed to [Go](/console/go) for Go.
+Usage counts toward your [member budget](/console/budgets#member-budgets). Use a key from a workspace with credits for
+pay-as-you-go, or from a workspace subscribed to [Go](/console/go) for Go.
+
+For shared machines or CI, owners and admins can create a [service account](/console/api#service-accounts) key instead,
+so usage isn't tied to one person.

 ## Base URLs

@@ -13,8 +13,7 @@ every Console model works.

 ## Configure

-Both providers read the key from `OPENCODE_API_KEY`. Create it under **Keys** in the
-[Console](https://opencode.ai/console).
+Both providers read the key from `OPENCODE_API_KEY`. Create a [personal API key](/console/harnesses#get-an-api-key).

 ```bash
 export OPENCODE_API_KEY="oc_sk_..."
@@ -12,8 +12,7 @@ Use Console and Go models in Raycast AI Chat, Quick AI, and AI Commands through
 The extension loads the models enabled in your workspace and bills them to it.

 1. Install the extension from the Raycast Store.
-2. Create a key under **Keys** in the [Console](https://opencode.ai/console) and paste it into the extension's
-   **API Key** preference.
+2. Create a [personal API key](/console/harnesses#get-an-api-key) and paste it into the extension's **API Key** preference.
 3. Allow the extension to provide models in the Raycast model picker.

 Run **Refresh Models** after enabling or disabling models in the Console.