> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chowder.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create API Key

> Generate a new API key scoped to specific instances and permissions.

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

<ParamField body="name" type="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.
</ParamField>

<ParamField body="instance_ids" type="string[]" required>
  Array of instance IDs this key should have access to.
</ParamField>

<ParamField body="permissions" type="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)       |
</ParamField>

<ParamField body="expires_at" type="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.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the key.
</ResponseField>

<ResponseField name="organization_id" type="string">
  The organization this key belongs to.
</ResponseField>

<ResponseField name="name" type="string">
  The name you gave the key.
</ResponseField>

<ResponseField name="key_prefix" type="string">
  Always `chd_sk_`. Useful for identifying Chowder keys in your configs.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether the key is currently active.
</ResponseField>

<ResponseField name="expires_at" type="string | null">
  Expiration datetime, if one was set.
</ResponseField>

<ResponseField name="created_at" type="string">
  When the key was created.
</ResponseField>

<ResponseField name="raw_key" type="string">
  The full API key, prefixed with `chd_sk_`. This is the value you'll use in `Authorization` headers.
</ResponseField>

<Warning>
  **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.
</Warning>

<RequestExample>
  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "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..."
  }
  ```
</ResponseExample>