Skip to main content
POST
/
v1
/
keys
curl -X POST https://api.chowder.dev/v1/keys \
  -H "Authorization: Bearer chd_sk_your_org_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Bot Key",
    "instance_ids": ["inst_abc123", "inst_def456"],
    "permissions": ["read", "interact", "channels"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

{
  "id": "key_9f8a7b6c",
  "organization_id": "org_1a2b3c4d",
  "name": "Production Bot Key",
  "key_prefix": "chd_sk_",
  "is_active": true,
  "expires_at": "2026-12-31T23:59:59Z",
  "created_at": "2026-02-14T12:00:00Z",
  "raw_key": "chd_sk_live_a1b2c3d4e5f6g7h8i9j0..."
}
Create an API key that grants access to one or more instances within your organization. Every key is scoped with explicit permissions so you can hand out only the access that’s actually needed.

​
Authorization

Requires an organization-level API key in the Authorization header.

​
Request Body

​
name
string
required
A human-readable name for the key. Pick something descriptive — you’ll thank yourself later when you’re staring at a list of keys.
​
instance_ids
string[]
required
Array of instance IDs this key should have access to.
​
permissions
string[]
required
Array of permission scopes to grant. Valid values:
PermissionWhat it unlocks
readView instance details and status
interactSend messages to the instance
configureModify instance settings and install skills
filesRead and write files in the instance workspace
channelsManage channels (create, update, delete)
​
expires_at
string
Optional ISO 8601 datetime string. If set, the key automatically becomes inactive after this time. If omitted, the key lives until you revoke it.

​
Response

​
id
string
Unique identifier for the key.
​
organization_id
string
The organization this key belongs to.
​
name
string
The name you gave the key.
​
key_prefix
string
Always chd_sk_. Useful for identifying Chowder keys in your configs.
​
is_active
boolean
Whether the key is currently active.
​
expires_at
string | null
Expiration datetime, if one was set.
​
created_at
string
When the key was created.
​
raw_key
string
The full API key, prefixed with chd_sk_. This is the value you’ll use in Authorization headers.
Store the raw_key immediately. This is the only time the full key is returned. We store a hash on our end — there’s no way to retrieve the raw value after this response.
curl -X POST https://api.chowder.dev/v1/keys \
  -H "Authorization: Bearer chd_sk_your_org_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Bot Key",
    "instance_ids": ["inst_abc123", "inst_def456"],
    "permissions": ["read", "interact", "channels"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

{
  "id": "key_9f8a7b6c",
  "organization_id": "org_1a2b3c4d",
  "name": "Production Bot Key",
  "key_prefix": "chd_sk_",
  "is_active": true,
  "expires_at": "2026-12-31T23:59:59Z",
  "created_at": "2026-02-14T12:00:00Z",
  "raw_key": "chd_sk_live_a1b2c3d4e5f6g7h8i9j0..."
}