API authentication
Usagey public usage endpoints accept a billing API key in the Authorization header.
Authorization: Bearer usg_test_replace_me
API keys are scoped to one billing workspace and therefore to one organization and environment.
Only secret keys can authenticate usage tracking and entitlement requests. Publishable keys are identifiers for explicitly public client-side integrations and are never accepted as server credentials.
After authentication, Usagey carries that organization, workspace, environment, and API-key actor into transaction-local database context before evaluating entitlements or recording usage. Idempotency records use the same tenant boundary, so a key cannot reuse another workspace's write record.
Keys are created only through an explicit authenticated action. Usagey reveals the raw secret once and stores only its hash, prefix, and final four characters. Workspace and API-key list responses never include the raw secret or its hash.
Workspace owners and administrators can assign an optional future expiry, revoke a key without deleting its audit metadata, or rotate it. Rotation atomically invalidates the previous secret and reveals the replacement once. An expired key must receive a future expiry, or have its expiry explicitly cleared, before it can be reactivated or rotated.
Catalog backfill does not generate a default secret because a background-generated key could not be revealed safely to an operator. Create the first key from Developer > API keys after workspace setup.
Never embed a Usagey API key in browser JavaScript, mobile binaries, logs, or public repositories. Send usage requests from your backend.
Missing and invalid keys return HTTP 401. Rotate a key from Developer → API keys if it may have been exposed.