Authentication

All /v1/* endpoints require a Bearer token API key. The health endpoint (GET /health) is public.

Authorization header

http

Authorization: Bearer shbx_<secret>

Scheme must be Bearer (case-insensitive).
The token is the full string shown once when you create a key in the dashboard (starts with shbx_).

bash

curl -H "Authorization: Bearer shbx_aBcDeFg..." \
  https://api.chck.ai/v1/account

The API hashes the token with SHA-256 (hex) and looks up platform_api_keys.token_hash.
The key must not be revoked (revoked_at is null).
The linked dashboard account must have role partner and a valid user_id.
All data returned by the API is scoped to that user.

last_used_at is updated asynchronously after a successful request.

On 401 responses the API may include:

http

WWW-Authenticate: Bearer realm="shoebox", error="invalid_request"

or error="invalid_token" for unknown or revoked keys. Integrations should not depend on the realm string for logic.

Do	Don't
Store keys in a secrets manager (Vault, AWS Secrets Manager, etc.)	Commit keys to git
Use one key per environment (staging / production)	Share keys in chat or email
Revoke compromised keys from the dashboard immediately	Embed keys in client-side code
Rotate keys periodically	Log full tokens in application logs