Create API Key

POST

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

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.

string[]

required

Array of instance IDs this key should have access to.

string[]

required

Array of permission scopes to grant. Valid values:

Permission	What it unlocks
`read`	View instance details and status
`interact`	Send messages to the instance
`configure`	Modify instance settings and install skills
`files`	Read and write files in the instance workspace
`channels`	Manage channels (create, update, delete)

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

string

Unique identifier for the key.

string

The organization this key belongs to.

string

The name you gave the key.

string

Always chd_sk_. Useful for identifying Chowder keys in your configs.

boolean

Whether the key is currently active.

string | null

Expiration datetime, if one was set.

string

When the key was created.

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..."
}

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..."
}

Overview

Organization

Instances

Channels

Skills

Files

API Keys

Subscription

Authorization

Request Body

Response

​Authorization

​Request Body

​Response

Authorization

Request Body

Response