Authentication

Create a token

An organization Owner, Admin, or Auth Admin can create a token from Settings > API tokens in Data Center.

1. Select the target organization.
2. Choose Create token.
3. Enter a descriptive application name and expiration.
4. Copy the dc_live_... value immediately.

The plaintext is displayed once. Butlr stores only a SHA-256 digest. Expiration is required and cannot exceed 365 days.

Send the token

Authorization: Bearer dc_live_...

Send it only from a trusted server-side client over HTTPS. Do not include it in a URL, WebSocket subprotocol, source file, browser bundle, or telemetry field.

Organization boundary

The token row contains the authorized organization ID. Resource authorization is repeated at each route. Supplying a different organization ID does not widen access, and a moved or ambiguously owned sensor fails closed.

Rotate and revoke

Before expiration:

1. Create a replacement token.
2. Update the consuming application’s secret.
3. verify the replacement with a low-volume read.
4. Revoke the old token from Settings > API tokens.

Revocation and expiration take effect on the next request. A revoked, expired, or unknown token returns 401 without revealing its lifecycle state.