# API keys (/docs/docklee/api-keys)
Every request to Docklee carries an API key as a bearer token. A key belongs to your workspace, and you decide what it can do and which engines and memory spaces it can reach.

<Callout type="info" title="Give each key the least it needs.">
- A chat front end that only answers questions needs `read`.
- A pipeline that only sends data needs `write`.
- A key for one product should reach only that product's engine and space.
</Callout>

## Create a key [#create-a-key]

In the [Docklee dashboard](https://app.docklee.com), open **API Keys** and create a key. Name it after where it runs, such as `support-bot-production`. You can add a note and an expiry date.

The full key appears once. Docklee keeps only a hash of the secret, so a lost key can't be shown again. Create a new one instead.

## Key format [#key-format]

A key looks like `dk_<public id>_<secret>`.

| Part | What it is |
| --- | --- |
| `dk_` | Marks the string as a Docklee key, so secret scanners can catch a leaked one. |
| Public ID | 12 characters that identify the key. The dashboard shows `dk_<public id>`, and it's safe to share with support. |
| Secret | The part that grants access. Treat the whole key as a password. |

## Capability [#capability]

Each key has one capability.

| Capability | Allows | Used by |
| --- | --- | --- |
| `write` | Writing data | `Dock` |
| `read` | Reading data | `Lynk` |
| `both` | Writing and reading | `Dock` and `Lynk` |

## Runtimes and scope [#runtimes-and-scope]

A key can reach **Knowledge Engines**, **DUM**, or both.

<Callout type="warn">
A new key starts with both runtimes and every engine and memory space in your workspace. Narrow it to selected engines and spaces in the dashboard before you ship it.
</Callout>

A request outside the key's runtimes or scope fails with `403`, even when the capability allows the action.

## Send the key [#send-the-key]

The SDK reads `DOCKLEE_API_KEY` from the environment. Over HTTP, send it in the `Authorization` header:

<CodeTabs>
  <Tab value="Python">
    ```python
    from docklee import Lynk

    lynk = Lynk()
    ```
  </Tab>
  <Tab value="TypeScript">
    ```ts
    import { Lynk } from 'docklee';

    const lynk = new Lynk();
    ```
  </Tab>
  <Tab value="cURL">
    ```bash
    curl https://api.docklee.com/v1/dum/search \
      -H "Authorization: Bearer $DOCKLEE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"memory_space_id": "your-memory-space-id", "query": "preferences", "top_k": 5}'
    ```
  </Tab>
</CodeTabs>

To pass a key in code, use `api_key` in Python or `apiKey` in TypeScript. In Python, `Dock` logs a warning when a key is passed in code and `DOCKLEE_API_KEY` isn't set, because a key written into source tends to end up in version control.

## Key status [#key-status]

| Status | Meaning |
| --- | --- |
| Active | The key works. |
| Needs rotation | The key works and is flagged for rotation. Rotate it soon. |
| Paused | A runtime policy has stopped the key. |
| Expired | The expiry date has passed, and the key no longer works. |
| Revoked | The key was revoked and returns `401`. |

## Rotate and revoke [#rotate-and-revoke]

**Rotate** gives the key a new secret and keeps its name, capability, and scope. The old secret stops working at once, so update every service that uses it right away.

To change keys with no downtime:

1. Create a second key with the same settings.
2. Deploy it to your services.
3. Confirm traffic is flowing on the new key.
4. Revoke the old key.

**Revoke** stops a key for good. If a key is exposed, revoke it right away and create a replacement.

## Keep keys safe [#keep-keys-safe]

- Store keys in environment variables or a secrets manager.
- Call Docklee from your server. Never ship a key in browser or mobile code.
- Use a separate key for each service and environment, so revoking one leaves the others running.
- Set an expiry date on keys you use for testing.

## Authentication errors [#authentication-errors]

| Status | Meaning | SDK error |
| --- | --- | --- |
| `401` | The key is missing, malformed, revoked, paused, or expired. | `AuthenticationError` |
| `403` | The key's capability, runtimes, or scope don't allow the request. | `PermissionDeniedError` |

## Next steps [#next-steps]

Your key is ready. Narrow its scope next, so it reaches only what your app uses.

<Cards>
  <Card title="Engines" href="/docs/docklee/engines" description="The engines a key can read from." />
  <Card title="Memory spaces" href="/docs/docklee/memory-spaces" description="The spaces a key can write to and recall from." />
  <Card title="Quickstart" href="/docs/docklee/quickstart" description="Use the key end to end." />
</Cards>
