API authentication

Every request to the Distribu REST API must include a Bearer token in the Authorization header. Keys are created in the dashboard, scoped to your company, and can be revoked at any time.

Creating a key

Navigate to Settings → API keys. Only OWNER and ADMIN staff can create keys (the page is empty for other roles).

Click + Create API key. The form asks for two things:

1. Key name — free-form, up to 100 characters. Examples: ERP integration, Shopify sync, Internal dashboard. The name shows up in the audit log and the key list — pick something you'll recognize six months from now.
2. Permissions — one or more scopes. Products — Read is preselected; pick whatever else the integration needs. See Scopes for what each unlocks.

Click Create key. You land on a screen showing the full plaintext key:

API key created! Copy it now — you won't see it again.

Your new API key:
  dk_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789-AbCdEfGhIjKl

Copy it immediately. The server stores only a SHA-256 hash of the key — the plaintext is shown exactly once. If you lose it, revoke and create a new one.

Key format

All keys start with the prefix dk_ and are followed by 32 random bytes encoded as base64url — so the full key is about 46 characters.

dk_<base64url-encoded 32 random bytes>

The first 12 characters (the prefix + first 9 random chars) are retained in plaintext for display purposes — shown in the API key list so you can identify a key without seeing its secret:

dk_AbCdEfGhI…

Using the key

Send it as a Bearer token in the Authorization header on every request:

curl https://distribu.app/api/v1/products \
  -H "Authorization: Bearer dk_AbCdEfGhIjKl..."

Anything else fails fast:

See Errors for the full response shape.

Viewing and revoking keys

The API keys page lists every active key:

Revoking is immediate — click the red Revoke link, confirm the prompt (Revoke "ERP integration"? Applications using this key will lose access immediately.), and the key stops authenticating on the very next request. There's no grace period.

Revoked keys move into a collapsed {N} revoked keys section at the bottom, kept so you can see what was used historically. They're never fully deleted.

Key lifecycle

• lastUsedAt — updated (fire-and-forget) every time the key authenticates. Use it to identify stale keys you can revoke.
• expiresAt — a key can optionally have an expiration date. The dashboard UI doesn't expose this setting today (all keys created from the UI are non-expiring), but we can set an expiry for you manually if you need a short-lived key.
• revokedAt — set when you click Revoke. Once set, the key is permanently dead.

Rotation

There's no built-in rotation flow yet. To rotate:

1. Create a new key with the same scopes.
2. Update your application to use the new key.
3. Revoke the old key.

During the overlap period, both keys authenticate — so you can roll out the change in your application without downtime.

Scoping to a single company

Every key is bound to a single company at creation. A key generated inside Acme Distributors can only read Acme's products and orders — it returns 404 Product not found. for resources outside its company, regardless of scope.

If you run multiple distinct businesses on Distribu (separate Companies), you need a separate key per company.

Audit trail

Every key-driven action is recorded:

Visible in Settings → Audit log.

Security notes

• Keys are secrets. Anyone with the plaintext can read (and, depending on scope, write) your company's data. Don't commit them to source control. Don't paste them into chat. Don't send them by email.
• Treat revoked keys as compromised. If you revoke a key because it leaked, assume whatever data its scopes allowed was exfiltrated. Check the audit log for unexpected activity on its last-used date range.
• Restrict scopes. A key that only reads products shouldn't carry orders:write. One scope per job.

Next: Scopes.