API reference
Secrets
Secrets hold the values a cloud run needs. They are write only: no route ever returns a value. Every route here is session only and needs an owner or admin. API keys are refused with 403, and members cannot manage secrets. Responses carry cache-control: no-store. How runs use secrets is on Organization secrets.
The secret object#
| Field | Type | Meaning |
|---|---|---|
id |
UUID | |
organization_id |
UUID | |
name |
string | ^[A-Z][A-Z0-9_]*$, at most 128 characters. |
created_at, updated_at |
date-time |
List secrets#
GET /v1/secrets?organization=<slug>
Response 200 { "secrets": [ ... ] }: names and timestamps only.
Set a secret#
PUT /v1/secrets
| Field | Type | Meaning |
|---|---|---|
organization_id |
UUID | Required. |
name |
string | Required. Upper snake case. |
value |
string | Required. At most 32,768 bytes of UTF-8. |
Creates the secret, or replaces its value when the name exists. Response 200: the secret, without its value. Each set is audited by name, never by value.
Delete a secret#
DELETE /v1/secrets/:id
Response 200 { "deleted": true }. Audited.
OpenRouter#
The organization's OpenRouter key is its OPENROUTER_API_KEY secret. These routes connect it by signing in with OpenRouter or by pasting a key. They are session only. Any member may read the status; connecting and pasting need an owner or admin. The key never appears in a response, error, or log.
| Method | Path | Body or query | Result |
|---|---|---|---|
| GET | /v1/openrouter |
query organization (slug) |
{ "connection" }, or { "connection": null } when none is saved. |
| POST | /v1/openrouter/grants |
{ "organization_id", "return_to": "secrets" or "onboarding" } |
201 { "authorization_url" }: send the user there to approve on OpenRouter. The sign-in expires after 10 minutes. |
| POST | /v1/openrouter/exchanges |
{ "code", "state" } from OpenRouter's redirect |
{ "organization_slug", "return_to" }. Saves the key OpenRouter issued. |
| PUT | /v1/openrouter/keys |
{ "organization_id", "key" } |
{ "connection" }. Saves a pasted key. |
connection is:
| Field | Meaning |
|---|---|
secret_id |
The OPENROUTER_API_KEY secret. |
saved_at, saved_by |
When and by whom it was saved. |
label |
The key's label on OpenRouter, or null. A key from sign-in is labelled <organization name> - Workbenches. |
credits |
{ "remaining_usd", "limit_usd" } when OpenRouter reports them, or null. |
key_hash |
SHA-256 of the key, or null. |