Skip to Content

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

PartWhat it is
dk_Marks the string as a Docklee key, so secret scanners can catch a leaked one.
Public ID12 characters that identify the key. The dashboard shows dk_<public id>, and it's safe to share with support.
SecretThe part that grants access. Treat the whole key as a password.

Capability

Each key has one capability.

CapabilityAllowsUsed by
writeWriting dataDock
readReading dataLynk
bothWriting and readingDock 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

StatusMeaning
ActiveThe key works.
Needs rotationThe key works and is flagged for rotation. Rotate it soon.
PausedA runtime policy has stopped the key.
ExpiredThe expiry date has passed, and the key no longer works.
RevokedThe 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:

  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

  • 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

StatusMeaningSDK error
401The key is missing, malformed, revoked, paused, or expired.AuthenticationError
403The 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.

On this page