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

# API-Key Management

> Create, copy, rename, expire, and revoke Duckie API keys

Manage Duckie API keys from **Settings -> API & MCP**.

The API & MCP section shows each key's name, preview, scopes, creator, created time, last-used time, expiration, and status.

It also includes an **MCP endpoint** panel with the endpoint URL, auth header format, JSON-RPC examples, and a connection test for a stored customer API key.

## Create a Key

<Steps>
  <Step title="Open API & MCP">
    Go to **Settings -> API & MCP**.
  </Step>

  <Step title="Create a key">
    Click **Create key**.
  </Step>

  <Step title="Name the key">
    Use a name that identifies the integration or environment, such as `Warehouse export` or `Production reporting`.
  </Step>

  <Step title="Choose scopes">
    Select the read scopes this key should have. All read scopes are selected by default.
  </Step>

  <Step title="Choose an expiration">
    Select **No expiration**, **90 days**, or **1 year**.
  </Step>

  <Step title="Store the key">
    Copy the full key from the one-time reveal dialog and store it in your secret manager.
  </Step>
</Steps>

<Warning>
  The full API key is shown only once. Duckie stores a hash and a preview after creation.
</Warning>

## Scopes

Scopes are grouped by how they are used.

### Customer API

These scopes control direct `/api/v1` requests.

| Scope label | Scope value           | Allows                                |
| ----------- | --------------------- | ------------------------------------- |
| Runs        | `api:runs:read`       | Read runs and run tool filter options |
| Tools       | `api:tools:read`      | Read tools                            |
| Agents      | `api:agents:read`     | Read agents                           |
| Guidelines  | `api:guidelines:read` | Read guidelines                       |
| Guardrails  | `api:guardrails:read` | Read guardrails                       |
| Runbooks    | `api:runbooks:read`   | Read runbooks                         |

### Duckie Assistant MCP

These scopes control the first-party Duckie Assistant MCP core object tools.

| Scope label        | Scope value      | Allows                                                       |
| ------------------ | ---------------- | ------------------------------------------------------------ |
| Core objects read  | `api:core:read`  | Describe, list, and retrieve core objects through MCP        |
| Core objects write | `api:core:write` | Create, update, and delete writable core objects through MCP |

Create separate keys for separate integrations when they need different scopes or rotation schedules.

MCP clients see only the wrapper tools allowed by the key's scopes. For example, a key with `api:runs:read` can list and retrieve runs through MCP, and a key with `api:core:write` can call MCP write tools for writable core objects.

## Rename a Key

Use rename when the integration name changes or you want a clearer label. Renaming changes only the display name. The API key value and scopes stay the same.

## Revoke a Key

Revoking a key stops new requests with that key immediately.

<Steps>
  <Step title="Find the key">
    Go to **Settings -> API & MCP** and find the key in the table.
  </Step>

  <Step title="Revoke">
    Click the revoke action and confirm.
  </Step>

  <Step title="Rotate integrations">
    Update any integration that used the revoked key with a newly created key.
  </Step>
</Steps>

## Statuses

| Status  | Meaning                                                          |
| ------- | ---------------------------------------------------------------- |
| Active  | The key can authenticate requests until it expires or is revoked |
| Expired | The key is past its configured expiration                        |
| Revoked | The key was manually revoked                                     |