Authentication

Send the Authorization header

Every v1 resource route authenticates an API key in the Authorization header. The request acts as the account that owns the key, subject to its scopes and the resource’s access checks.

Authorization: Bearer flv1_<lookup-uuid>_<masked-secret>

The token has an flv1_ prefix, a lookup UUID and a secret, separated by underscores. The secret is generated from 32 random bytes and encoded as base64url. This masked example is not a usable key.

Keep the token private

Store the token in a server-side environment variable or secret store. Use $FLORALITY_KEY in terminal examples and read the environment on your server. Do not expose the token in client-side code, logs or shared snippets.

The service stores a salted secret hash and returns the plaintext token at creation or rotation. Copy it when it is revealed.

Rotate or revoke a key

Open API keys in the dashboard to change scopes, rotate or revoke a key. Rotation creates a replacement with the existing name and access settings.

Revocation marks the key as revoked. It is excluded from authentication and the active-key count. There is no expiry field or time-based expiry check in the current implementation, so there is no separate “expired key” response.

Handle authentication failures

Missing, malformed, incorrect and revoked tokens return HTTP 401 with the same body:

{
  "code": "UNAUTHORIZED",
  "message": "Missing or invalid API key. Use Authorization: Bearer <token>."
}

A valid key without the required scope returns HTTP 403. For example, a member read request can return:

{
  "code": "FORBIDDEN",
  "message": "Missing API key scope: members requires read"
}

Fix the key or its permissions before retrying. Resource-level ownership or friend-access checks still apply after scope authentication.