Scoped API Keys

Your organization API key (chd_org_...) is the master key. It can do everything — create instances, delete them, manage billing. You absolutely should not put it in a frontend, a mobile app, or hand it to a third-party integration. That’s where scoped keys come in. A scoped key (chd_sk_...) is locked down to specific instances and specific permissions. It can only do what you allow.

Why scoped keys?

Frontends: Your chat UI only needs to send messages and read status. Give it read + interact, nothing else.
Integrations: A Zapier workflow that installs skills? Give it configure on one instance.
End users: Give each user a key scoped to their instance with interact only. They can chat but can’t touch config.
Time-limited access: Set expires_at and the key auto-revokes.

Set up

export CHOWDER_KEY="chd_org_your_key_here"
export INSTANCE_ID="your-instance-id"

Permission reference

Here’s every permission you can assign to a scoped key:

Permission	What it grants
`read`	View instance details and status (`GET /v1/instances/{id}`, `GET /v1/instances/{id}/status`)
`interact`	Send messages and receive responses (`POST /v1/instances/{id}/responses`, session responses)
`configure`	Update instance config, manage skills (`PATCH /v1/instances/{id}`, skills endpoints)
`files`	Read, write, delete, and move files in the instance workspace
`channels`	Connect, disconnect, and manage messaging channels

For a typical chat frontend, ["read", "interact"] is all you need. Start minimal and add permissions only when required.

Multi-instance keys

A single scoped key can access multiple instances with the same permissions:

curl -X POST https://api.chowder.dev/v1/keys \
  -H "Authorization: Bearer $CHOWDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dashboard-key",
    "instance_ids": [
      "ead7b76b-f34e-4b91-93e7-9c979cf9e41c",
      "c4a91d3e-8f2b-4e7a-b5c6-2d9f1e8a4b73",
      "f7e23b8d-1a4c-4d96-9e5f-3b7c2d8a1e64"
    ],
    "permissions": ["read", "interact", "configure"]
  }'

This is useful for admin dashboards that need to manage a fleet of instances.

Common patterns

Chat frontend
Admin dashboard
Temp demo access

{
  "name": "web-chat",
  "instance_ids": ["<instance-id>"],
  "permissions": ["read", "interact"]
}

Minimal access. Can read status and send messages. Can’t change config, manage channels, or delete anything.

{
  "name": "admin-panel",
  "instance_ids": ["<id-1>", "<id-2>", "<id-3>"],
  "permissions": ["read", "interact", "configure", "files", "channels"]
}

Full access to specific instances, but still can’t create/delete instances or manage billing (that requires the org key).

{
  "name": "demo-2026-02",
  "instance_ids": ["<instance-id>"],
  "permissions": ["read", "interact"],
  "expires_at": "2026-02-28T23:59:59Z"
}

Auto-expires at end of month. Great for demos or trial access.

What’s next?

Build a Frontend

Put that scoped key to use in a Next.js chat interface.

Connect Telegram

Wire up a messaging channel to your agent.

Getting Started

Core Concepts

Guides

Scoped API Keys

Why scoped keys?

Set up

Permission reference

Multi-instance keys

Common patterns

What’s next?

Build a Frontend

Connect Telegram

​Why scoped keys?

​Set up

​Permission reference

​Multi-instance keys

​Common patterns

​What’s next?

Build a Frontend

Connect Telegram

Why scoped keys?

Set up

Permission reference

Multi-instance keys

Common patterns

What’s next?