docs / auth

Auth & tokens

Every call krabs sees must carry a bearer token. Tokens are scoped, rotatable, and never logged.

Token format

Tokens follow the shape krabs_sk_<base32>. The body after the prefix is exactly 40 characters of Crockford base32 entropy.

krabs_sk_4n7q2vh3jpz9w8x1y0c5b6d4f8g2k1m3

Tokens are shown once at creation. We store an Argon2id hash; the plaintext never touches the database, the logs, or any error report.

shown once

If you close the modal without copying the token, you cannot recover it. Rotate the key to issue a new one — the lost token is dead weight, not a security risk.

Minting keys

From the web dashboard at /dashboard/keys, or via CLI:

krabs auth tokens create --label "my agent"

Output:

key_id: key_01HGZ9X4QY8M2N7P3R5T6V8W
label:  my agent
scope:  full
token:  krabs_sk_4n7q2vh3jpz9w8x1y0c5b6d4f8g2k1m3
        ↑ copy now, you will not see this again

Scopes

A token carries exactly one scope. Granular per-resource scopes ship in v0.5.

scope	description	default
`full`	read and write across every namespace	✓
`read`	read across every namespace, no mutations
`write`	read and write, blocks `account.*` and key management
`audit-read`	read access limited to the append-only audit log

Using the token

HTTP — standard bearer header:

Authorization: Bearer krabs_sk_4n7q2vh3jpz9w8x1y0c5b6d4f8g2k1m3

CLI — environment variable:

export KRABS_API_KEY=krabs_sk_4n7q2vh3jpz9w8x1y0c5b6d4f8g2k1m3
krabs contact list

MCP — embedded in the host config:

{
  "mcpServers": {
    "krabs": {
      "url": "https://mcp.krabs.dev",
      "auth": { "type": "bearer", "token": "krabs_sk_…" }
    }
  }
}

Rotation

Rotate a key without changing its id. The old token is invalidated immediately; the new token is shown once.

krabs auth tokens rotate key_01HGZ9X4QY8M2N7P3R5T6V8W

All metadata — label, scope, audit history — stays attached to the key id. Agents that reference the key by id (CI secrets, vault entries) only need their secret updated, not their config.

Revocation

From the dashboard, or CLI:

krabs auth tokens revoke key_01HGZ9X4QY8M2N7P3R5T6V8W

The row is soft-deleted. Every subsequent call presenting that token returns auth_revoked with the timestamp and actor of revocation.

Errors

code	meaning	recovery
`auth_missing`	no `Authorization` header on the request	attach a bearer token
`auth_invalid`	token does not match any known key hash	verify the value, mint a new one if lost
`auth_expired`	token TTL has elapsed (rare; only for short-lived OAuth-issued tokens)	re-authenticate or mint a long-lived key
`auth_revoked`	key id was explicitly revoked	rotate or mint a replacement, update the caller

Edit this page on GitHub →last updated 2026-05-16 · v0.4.3