Distribu

API keys

API keys authenticate external integrations with the Distribu REST API. This page covers the dashboard UI for managing them. For the consumer side — how to send the Authorization header, how keys are validated — see Authentication.

OWNER or ADMIN only. MEMBERS cannot view or create keys. Find the page at /dashboard/settings/api-keys.

What's on the page

The API keys page lists every key created for your company with:

ColumnNotes
NameHuman-readable label you supplied at creation.
PrefixFirst 12 chars of the key (e.g. dk_AbCdEf12). Safe to show publicly — the full key is never recoverable from the prefix.
ScopesThe permission flags selected at creation.
Last usedTimestamp of the most recent successful API call with this key. null if never used.
CreatedWhen the key was created and by whom.
StatusActive, Revoked, or Expired.

Revoked and expired keys remain in the list for audit purposes but can't authenticate any requests.

Creating a key

Click + New key. The form asks for:

  • Name — required, up to 100 chars. Pick something that identifies which integration uses the key (e.g. "NetSuite sync", "BI dashboard — read-only").
  • Scopes — one or more permission flags. products:read is preselected; all nine are opt-in. See Scopes for the full list and recommended combinations.

On submit, Distribu generates the key, shows it once, and immediately hides the value again:

Your API key (copy it now — you won't see it again):
  dk_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGhIjKlMnOp

Keys are 32 random bytes, base64url-encoded, prefixed with dk_ — about 47 characters total. Store it in a password manager or secret store; if you lose it you'll need to revoke and create a new one.

The key is only hashed in the database. Distribu stores a SHA-256 hash of the key — the plaintext is never persisted, so neither Distribu staff nor support can recover a lost key.

Revoking a key

Click Revoke next to any active key, confirm, and the key stops authenticating immediately. Subsequent calls get 401 Invalid or revoked API key.

Revocation is irreversible — create a new key if you need one again.

Use revocation when:

  • The key's credentials may have leaked (e.g. committed to a public repo).
  • An integration is retired and the key is no longer needed.
  • Someone left the team who had the plaintext key.

Rotating a key

There's no "rotate" button — the flow is:

  1. Create a new key with the same scopes.
  2. Update your integration's environment variable to the new key.
  3. Deploy / restart.
  4. Watch the old key's Last used column until it stops advancing.
  5. Revoke the old key.

This is a zero-downtime rotation because both keys validate during the overlap window.

Auditing key activity

Every API key action writes an audit log entry:

ActionWhen
api_key.createdKey created. Metadata: name, scopes.
api_key.revokedKey revoked. Metadata: key ID.

Each API call the key makes is not written to the audit log individually (that would be noisy); instead, the lastUsedAt timestamp on the key row is updated fire-and-forget on every successful call. See Audit log for the filter UI.

Best practices

  • One key per integration. Revocation is per-key, so a leaked credential only takes down the one integration. See Scopes → One key per integration.
  • Narrowest scope that works. A BI tool needs products:read/orders:read/customers:read/reports:read — not orders:write. If it leaks, the blast radius is "someone can see my data," not "someone can create bogus orders."
  • No keys in source control. Load from environment variables (DISTRIBU_API_KEY) or a secret store. Pre-commit hooks that scan for dk_[A-Za-z0-9_-]{40,} are a cheap safety net.
  • Rotate on a schedule. Every 90 days is a reasonable default. The "create-new → cut-over → revoke-old" flow above is zero-downtime at any cadence.

What's not here (yet)

  • Expiration dates. The data model has an expiresAt column, but the dashboard form doesn't expose it yet. All keys are effectively non-expiring until revoked.
  • IP allow-lists. No per-key IP restrictions today.
  • Per-request audit entries. Only create / revoke are audited. API call logs are in application-level logs, not the audit log.
  • Programmatic API-key management. No /api/v1/api-keys endpoint — keys are dashboard-managed only.

Related:

  • Authentication — how a key is used in API requests.
  • Scopes — permission values and their endpoint mappings.
  • Audit log — filter for api_key.created / api_key.revoked events.