Workflows

Workflows: Mint and revoke API keys

Mint per-human and service-class keys, and revoke when access ends.

Prerequisites

acaso_os:admin on the connection. Key administration in v1 is admin-gated.
The bootstrap alternative (python -m datahub.interface.cli.bootstrap, run by the deployment) mints the tenant admin key outside the console; useful only for first connection.

Mint a key from the CLI

The fastest path for the first key on a new tenant:

bash

python -m datahub.interface.cli.bootstrap

The command prints the key value once. Save it in your password manager; it cannot be retrieved later. Running it again creates a new key in parallel without revoking the old one.

Warning: A long-lived key bound to a user inherits the user's roles. For a key with limited scopes, mint it via the console with a curated scope list.

Mint a key from the console

Open /tenants/{slug}/keys and click Mint key. The form:

Field	Description
Name	Cosmetic label.
Kind	`human` (bound to a user, used by the console) or `service` (unbound, for backend integrations).
Bound user	Required for `kind=human`. Pick from the tenant's user list.
Role	Optional. The key inherits this role's scopes.
Extra scopes	Optional. Additional scopes layered on top of the role.

Submit calls POST /v1/admin/tenants/{slug}/api-keys. The full key value is returned exactly once in a modal banner labelled "Copy now — this key cannot be retrieved later". A one-click copy button is provided. Closing the banner removes the key from the DOM.

Revoke a key

Open the key list, find the row, click Revoke. The confirmation requires you to type the key's prefix to confirm. On confirmation the console calls DELETE /v1/admin/tenants/{slug}/api-keys/{key_id}.

Revocation has three immediate effects:

The key row is marked revoked. It stays in the table greyed-out for audit history.
Every session key whose parent_key_id is this key is invalidated server-side within the Redis cache TTL (roughly 60 seconds).
The audit log records action = api_key.revoke.

Warning: Revoking a key kills every browser session derived from it. Confirm with the key's owner before revoking unless this is an incident response.

Session keys

Session keys (kind=session) are minted automatically by POST /v1/auth/session and are NOT visible in the regular key list. They expire 8 hours after creation and are hard-deleted from dh_api_keys 7 days after expiry by the cleanup job.

To force-expire every active session for one parent key, revoke the parent. There is no UI to revoke individual sessions in v1.

Mint a key from the CLI

The fastest path for the first key on a new tenant:

bash

python -m datahub.interface.cli.bootstrap

The command prints the key value once. Save it in your password manager; it cannot be retrieved later. Running it again creates a new key in parallel without revoking the old one.

Warning: A long-lived key bound to a user inherits the user's roles. For a key with limited scopes, mint it via the console with a curated scope list.

Mint a key from the console

Open /tenants/{slug}/keys and click Mint key. The form:

Field

Description

Name

Cosmetic label.

Kind

human (bound to a user, used by the console) or service (unbound, for backend integrations).

Bound user

Required for kind=human. Pick from the tenant's user list.

Role

Optional. The key inherits this role's scopes.

Extra scopes

Optional. Additional scopes layered on top of the role.

Revoke a key

Revocation has three immediate effects:

The key row is marked revoked. It stays in the table greyed-out for audit history.

Every session key whose parent_key_id is this key is invalidated server-side within the Redis cache TTL (roughly 60 seconds).

The audit log records action = api_key.revoke.

Warning: Revoking a key kills every browser session derived from it. Confirm with the key's owner before revoking unless this is an incident response.

Session keys

To force-expire every active session for one parent key, revoke the parent. There is no UI to revoke individual sessions in v1.