From 235900b9e508a86e2b795a969d7b1c83292bbf14 Mon Sep 17 00:00:00 2001 From: Rajat Ahuja Date: Thu, 3 Sep 2026 16:01:54 -0400 Subject: [PATCH] docs for programmatically creating api key (#1133) * docs for programmatically creating api key * chore: adtl reference to the create-key endpoint * fix: enhance docs --------- Co-authored-by: ajspig --- docs/v3/api-reference/endpoint/keys/create-key.mdx | 14 ++++++++------ docs/v3/documentation/reference/platform.mdx | 2 +- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/v3/api-reference/endpoint/keys/create-key.mdx b/docs/v3/api-reference/endpoint/keys/create-key.mdx index 9f9b0470..db6a34b1 100644 --- a/docs/v3/api-reference/endpoint/keys/create-key.mdx +++ b/docs/v3/api-reference/endpoint/keys/create-key.mdx @@ -3,11 +3,13 @@ openapi: post /v3/keys --- -**Self-hosted only.** This endpoint is not available on Honcho Cloud -(`api.honcho.dev`) — requests to it return `405 Method Not Allowed`. Create and -manage keys for a cloud instance from the -[API Keys page](https://app.honcho.dev/api-keys) in the dashboard. +Requires an admin key. On Honcho Cloud (`api.honcho.dev`) the returned key is a +real cloud key on the calling key's instance, attributed to its owner and +revocable from the [API Keys page](https://app.honcho.dev/api-keys). On a +self-hosted instance it returns an error when `AUTH_USE_AUTH` is disabled. -On a self-hosted instance it requires an admin key, and returns an error when -`AUTH_USE_AUTH` is disabled. +Provide at least one of `workspace_id`, `peer_id`, or `session_id` — a request +carrying none of them is rejected. A key scoped to a peer or a session must also +carry its `workspace_id`. On Honcho Cloud, pass either `admin=true` or a +`workspace_id`. diff --git a/docs/v3/documentation/reference/platform.mdx b/docs/v3/documentation/reference/platform.mdx index 28042d4c..8e32d3d8 100644 --- a/docs/v3/documentation/reference/platform.mdx +++ b/docs/v3/documentation/reference/platform.mdx @@ -62,7 +62,7 @@ The **Performance** page provides comprehensive monitoring with usage metrics, h ## 3. Manage API Keys The [API Keys](https://app.honcho.dev/api-keys) page allows you to create and manage authentication tokens for different environments. You can create admin-level keys with full instance access or scope keys to a specific `Workspace`, `Peer`, or `Session`. -Keys for a cloud instance can only be created here, not through the API — `POST /v3/keys` is disabled on `api.honcho.dev` and returns `405`. The same applies to the webhook management endpoints, which live on the [Webhooks](https://app.honcho.dev/webhooks) page. +Keys can also be created programmatically. `POST /v3/keys` with an admin key returns a real cloud key on that key's instance, attributed to its owner and revocable from the [API Keys](https://app.honcho.dev/api-keys) page. Scoped keys are authorized by their narrowest claim and never widen to the whole workspace: