Authentication

Summary

Every RedCloud API request is authenticated and tenant-scoped. The API supports several credential types, checked in priority order. For automation, use a per-user API key.

Credential types

Type	Header	Notes
Master key (break-glass)	X-Master-Key (+ X-Break-Glass-Reason in production)	Governed, scoped, audited; off by default
JWT session	Authorization: Bearer <token>	The web UI’s session mechanism
Per-user API key	X-API-Key: cspm_…	Recommended for automation; verified against the DB
Global API key	X-API-Key: <configured key>	Legacy; restricted role in production

If no valid credential is supplied, production returns 401 UNAUTHORIZED.

Using an API key

Create a key under Administration → User Management → API Keys, then send it in the X-API-Key header:

curl "https://<your-host>/scans" \
  -H "X-API-Key: cspm_xxxxxxxxxxxxxxxx"

Per-user keys carry the permissions of their role, resolved live from the database on each request (so role changes take effect within seconds). If key verification can’t reach the database, the request fails closed (503), never downgrading to a weaker credential.

JWT sessions

The web app logs in via POST /auth/login (email/password, optionally with a TOTP code), which returns an access token (short-lived) and a refresh token. Send the access token as Authorization: Bearer <token>; rotate with POST /auth/refresh.

Tenant context

The authenticated identity determines the tenant; the API sets it from the JWT’s tenant_id. The X-Tenant-ID request header is honored only for sufficiently privileged users (master, or both admin.users and admin.settings). The resolved tenant is echoed in the X-Tenant-ID response header. There is no cross-tenant access.

Break-glass (master key)

The master key is for emergencies: disabled by default, enabled only with BREAK_GLASS_ENABLED=true and a configured MASTER_KEY, rate-limited, time-bounded, and fully audited. It grants a scoped permission set — never a wildcard — and never bypasses tenant isolation.

Examples

# Login (JWT)
curl -X POST "https://<your-host>/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"me@example.com","password":"…"}'

# Use the access token
curl "https://<your-host>/auth/me" \
  -H "Authorization: Bearer <access_token>"

Notes & limitations

• All endpoints are also available under an /api/v1 prefix (see Endpoints).
• Every request carries an X-Correlation-ID you can quote to support.
• Some endpoints additionally require MFA or a licensed feature — see Permissions & Scopes.