Keys and access

Datalumo has three kinds of key. Each is for a different place. Keeping them straight is the whole game:

Key Looks like Lives Can do
Admin key dlk_… Your server, CLI, backend Everything
Publishable key pk_… Your web page (public) Mint widget tokens only
Client token dlt_… The visitor's browser, short-lived Search and chat for one app

These are separate from your AI provider key (OPENAI_API_KEY and friends), which only talks to the model provider and never grants access to Datalumo.

Send a key as Authorization: Bearer <value>.

Admin key

Full access. Use it for the CLI, ingesting content, and your own backend. The installer creates one on first boot and prints it. To see it again:

docker compose exec datalumo cat /app/data/admin-key

Never put an admin key in a web page, theme file, or public repo. It can do everything.

Publishable key (for the widget)

The widget runs in the browser, so it can't hold your admin key. Instead it uses a publishable key, which is safe to expose because it can only do one thing: mint a short-lived token for an app you've allowed, on a domain you've allowed.

Create one in admin under your app's Deploy tab. Two settings matter:

  • Origins: the domains allowed to use this key. Always set this in production. An empty list means any site can use it.
  • Scopes: what it allows. Pick from search, chat, summarize, and events. Turn on only what that site needs.

Client token

You rarely handle these directly. When someone loads your widget, the publishable key mints a client token behind the scenes. It's tied to one app, lasts about fifteen minutes, and can only search and chat. Expired tokens are cleaned up automatically.

If your users are logged in and you want chat history tied to them, mint tokens from your own backend instead, with the admin key, and pass an owner id. See "Tie access to your own logins" below.

Protect your spend

Because the widget is public, set limits before you expose a publishable key. Two that matter most:

  • spend.dailyTokenCeiling: a hard cap on AI tokens per day for the whole instance.
  • auth.clientTokens.perTokenSpendCap: a cap per browser token, so one visitor can't run up a bill.

Datalumo also rate-limits requests and token minting per IP. See Configuration.

Tie access to your own logins

For a static site, the publishable key is all you need. If you want widget access to follow your own user accounts, have your backend mint tokens:

  1. Your server calls POST /v1/tokens with the admin key, sets an owner id and scopes.
  2. It returns { token, expiresAt } to your page.
  3. The widget uses data-token-endpoint="https://yoursite.com/api/datalumo-token" to fetch them.

Rotating and revoking

  • Publishable key: revoke it under Deploy, create a new one, update your embed snippet.
  • Admin key: manage keys under System in admin, or edit your config and restart.
  • Client tokens: revoke under System, or let them expire.

Before you go live

  • Admin key kept on the server, never in a browser or git.
  • Daily token ceiling set.
  • Per-token spend cap set, if you use publishable keys.
  • Every publishable key has a non-empty origin list.
  • TLS in front of the instance (the bundled Caddy, or your own proxy).

Run dl doctor to check most of this for you.