RomanNum3ral
/
honcho
mirror of https://github.com/plastic-labs/honcho.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 <dragon@monstercode.com>
This commit is contained in:
Rajat Ahuja 2026-09-03 16:01:54 -04:00 committed by GitHub
parent afbc517cbc
commit 235900b9e5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 9 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/v3/api-reference/endpoint/keys/create-key.mdx
View File

@ -3,11 +3,13 @@ openapi: post /v3/keys
---
<Note>
**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`.
</Note>

2
docs/v3/documentation/reference/platform.mdx
View File

@ -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: