Getting Started
API keys
Create a key, choose what it can do and reach, send it with each request, and rotate it without downtime.
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.
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.
Create a key
In the Docklee dashboard, 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
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
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
A key can reach Knowledge Engines, DUM, or both.
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.
A request outside the key's runtimes or scope fails with 403, even when the capability allows the action.
Send the key
The SDK reads DOCKLEE_API_KEY from the environment. Over HTTP, send it in the Authorization header:
from docklee import Lynk
lynk = Lynk()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
| 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 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:
- Create a second key with the same settings.
- Deploy it to your services.
- Confirm traffic is flowing on the new key.
- 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
- 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
| 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
Your key is ready. Narrow its scope next, so it reaches only what your app uses.