API tokens

Named, revocable secrets for apps - each acts as one user, and DROP TOKEN stops it at once.

• Category: Users & security
• Keywords: API token, api tokens, token, tokens, CREATE TOKEN, DROP TOKEN, SHOW TOKENS, revoke, revoke token, kdbt_, Bearer, Authorization, EXPIRES, personal access token, service token, app token, 401
• See also: Users and roles, Logins, tokens and roles over HTTP, Keeping kdb serve safe, Protection - timeouts, limits, safe updates, read-only

An API token is a long secret an app sends with every request, like the server's --token. The difference: you can have many, each has a name, each acts as one user (with that user's rights), and you can remove one without touching the others.

Give each app its own token. When one app is retired or its secret leaks, drop that token; the other apps go on.

Example: A token for the chart app, a read-only user

Setup:

CREATE USER admin WITH PASSWORD 'Long-Admin-Passw0rd' ROLE admin;
CREATE USER charts WITH PASSWORD 'Chart-app-secret-11' ROLE read;

CREATE TOKEN chart_app FOR USER charts EXPIRES IN 90 DAYS;
SHOW TOKENS;

Result:

CREATE TOKEN chart_app FOR USER charts EXPIRES IN 90 DAYS

(1 row)

token 'chart_app' for user 'charts' created: copy it now, it is shown only this once. Send it as Authorization: Bearer <token>

SHOW TOKENS

(1 row)

CREATE TOKEN

Syntax:

CREATE TOKEN name [FOR USER user] [EXPIRES IN n DAYS]

Makes a new token and shows its secret once.

• Returns: one row name, user, token, expires. The token looks like kdbt_ and 43 more letters. Copy it now: KDB keeps only its SHA-256, so nobody can show it again.
• Notes:
  • Any user may make a token for themselves. A token for another user needs ROLE admin.
  • The app sends it as Authorization: Bearer kdbt_... on the HTTP API (/exec, /write, /imp, /api/...). It is not a password for the PostgreSQL port; use the user's password there.
  • It can do exactly what its user can do, including table rights, the user's time limit and rate limit. For a read-only app, make a user with ROLE read and a token for it.
  • A new password for the user does not end the user's tokens (apps keep working). DROP USER removes the user's tokens.
  • The session that runs it needs a user: with the server's --token or in kdb sql, write FOR USER.

Example: Two apps, two tokens for one user

Setup:

CREATE USER admin WITH PASSWORD 'Long-Admin-Passw0rd' ROLE admin;
CREATE USER loader WITH PASSWORD 'Loader-secret-long-5' ROLE write;

CREATE TOKEN price_feed FOR USER loader;
CREATE TOKEN backfill FOR USER loader EXPIRES IN 7 DAYS;

Result:

CREATE TOKEN price_feed FOR USER loader

(1 row)

token 'price_feed' for user 'loader' created: copy it now, it is shown only this once. Send it as Authorization: Bearer <token>

CREATE TOKEN backfill FOR USER loader EXPIRES IN 7 DAYS

(1 row)

token 'backfill' for user 'loader' created: copy it now, it is shown only this once. Send it as Authorization: Bearer <token>

Example: The name is taken (shows an error)

Setup:

CREATE USER admin WITH PASSWORD 'Long-Admin-Passw0rd' ROLE admin;
CREATE TOKEN price_feed FOR USER admin;

CREATE TOKEN price_feed FOR USER admin;

Result:

Error: token 'price_feed' already exists

Example: A token acts as a user (shows an error)

Setup:

CREATE USER admin WITH PASSWORD 'Long-Admin-Passw0rd' ROLE admin;

CREATE TOKEN price_feed;

Result:

Error: CREATE TOKEN needs FOR USER <name> here: this session has no user (the server's --token, or a local tool), and a token always acts as one user

DROP TOKEN

Syntax:

DROP TOKEN [IF EXISTS] name

Revokes a token. Every request with it gets 401 from then on: the API token is wrong, has expired or was dropped (SHOW TOKENS).

• Returns: token 'name' dropped: it stops working at once.
• Notes: a user may drop their own tokens; other users' tokens need ROLE admin.

Example

Setup:

CREATE USER admin WITH PASSWORD 'Long-Admin-Passw0rd' ROLE admin;
CREATE TOKEN price_feed FOR USER admin;

DROP TOKEN price_feed;
DROP TOKEN IF EXISTS price_feed;

Result:

DROP TOKEN price_feed

token 'price_feed' dropped: it stops working at once

DROP TOKEN IF EXISTS price_feed

token 'price_feed' does not exist

SHOW TOKENS

Syntax:

SHOW TOKENS

Lists the tokens. Never the secrets: only the first letters, so you can tell which one an app has.

• Notes: an admin sees every token; other users see their own. The web console lists them on the Settings page, where you can make and remove them too.

Example

Setup:

CREATE USER admin WITH PASSWORD 'Long-Admin-Passw0rd' ROLE admin;
CREATE TOKEN price_feed FOR USER admin EXPIRES IN 30 DAYS;

SHOW TOKENS;

Result:

(1 row)

Where tokens and logins are kept

Both live in the hidden _system database of the data folder, as hashes only:

So a server restart logs nobody out, and apps with a token go on. A login still ends after 12 hours, at logout, or when the user gets a new password or is dropped. An older KDB program does not know these tables: there, tokens do not work and everyone logs in again.