> ## 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.

# Authentication

> Authenticate Duckie API requests with bearer API keys

Duckie API requests use API keys created in Duckie. Send the full key in the `Authorization` header using the bearer scheme.

```http theme={null}
Authorization: Bearer dk_live_your_api_key
```

## Create an API Key

Create keys from **Settings -> API & MCP**. The full key is shown once after creation, so store it before closing the dialog.

Keys start with `dk_live_`. Duckie stores only a hash and a display preview after creation.

## Example Request

```bash theme={null}
curl "https://app.useduckie.ai/api/v1/tools?type=custom_tool" \
  -H "Authorization: Bearer dk_live_your_api_key"
```

## Scopes

Every key has one or more scopes. A request fails with `403 permission_denied` when the key does not include the required scope.

| Scope                 | Allows                                |
| --------------------- | ------------------------------------- |
| `api:runs:read`       | Read runs and run tool filter options |
| `api:tools:read`      | Read tools                            |
| `api:agents:read`     | Read agents                           |
| `api:guidelines:read` | Read guidelines                       |
| `api:guardrails:read` | Read guardrails                       |
| `api:runbooks:read`   | Read runbooks                         |
| `api:core:read`       | Read core objects through MCP         |
| `api:core:write`      | Write core objects through MCP        |

The create-key dialog groups scopes into Customer API scopes and Duckie Assistant MCP scopes. You can remove scopes when you want a key to access only a subset of the API or MCP tools.

## Invalid or Expired Keys

The API returns `401 unauthenticated` when a key is missing, malformed, unknown, expired, or revoked.

```json theme={null}
{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid API key",
    "request_id": "req_123"
  }
}
```

Revoking a key in Settings stops new requests with that key immediately.