Authentication¶

The b'nerd API supports two authentication methods. Both are sent in the same Authorization header as a Bearer token.

JWT bearer tokens (interactive sessions)¶

JWT tokens are short-lived and tied to a specific user account. Use them for interactive sessions in the dashboard, CLI, or scripts that can refresh tokens.

Obtain a token¶

# 1. Create an account (first-time only)
curl -X POST https://api.bnerd.cloud/create-account \
  -H "Content-Type: application/json" \
  -d '{
    "login": "you@example.com",
    "name": "Your Name",
    "password": "...",
    "password-confirm": "...",
    "organization_name": "ACME Corp"
  }'
# => {"success":"An email has been sent to you with a link to verify your account"}

# 2. Verify your email, then log in
curl -X POST https://api.bnerd.cloud/login \
  -H "Content-Type: application/json" \
  -d '{"login": "you@example.com", "password": "..."}' -i
# => Authorization: eyJhbGciOiJIUzI1NiJ9...

The Authorization response header contains your JWT. Use it in subsequent requests:

curl https://api.bnerd.cloud/accounts/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

Static API tokens (machine-to-machine)¶

Static tokens are long-lived, org-scoped tokens intended for CI/CD pipelines, the Terraform provider, and automated scripts. They do not expire on their own and are managed through the dashboard or API.

Static tokens carry the same Bearer prefix:

curl https://api.bnerd.cloud/projects \
  -H "Authorization: Bearer bnerd_tok_..."

Scoping¶

Static tokens are scoped to an organization. Requests made with a static token operate as if the token owner's permissions apply within that organization. Fine-grained write operations (e.g. quota and lock changes on RGW users) still require admin-level permissions on the organization — a static token issued for a member-role account cannot escalate privileges.

Which token to use¶

Unauthenticated endpoints¶

A small number of endpoints are public (no token required):

• GET /invite/{token} — show an invitation by token
• PATCH /invite/{token}/accept — accept an invitation by token
• PATCH /invite/{token}/decline — decline an invitation by token
• GET /invitations/details?token=... — look up invitation details

All other endpoints return 401 Unauthorized when no valid token is provided.