API · Authentication

The Usetix API authenticates every request with a bearer token. Tokens are account-scoped — a token issued for one account never sees another account’s data — and come in two permission tiers: read and write.

Generating a token

API tokens live in your admin dashboard at Settings → API Tokens.

1. Click Token to generate a new token.
2. Give it a recognizable description (e.g. Mailchimp sync) so you can audit later.
3. Pick a permission tier:
   • Read — allows GET and HEAD only. Safe for analytics, dashboards, and read-only sync jobs.
   • Read + Write — allows all methods. Use for integrations that create or modify data on your behalf.
4. Click Create Token. The full token value is shown once on the next screen for ten seconds; copy it into your integration before navigating away. After that, only the description and permission tier remain visible.

Treat your token like a password. Anyone with the token can read (or write to) your Usetix account. Don’t commit it to a public repo, embed it in client-side code, or share it over insecure channels.

Using a token

Include the token in the Authorization header on every request, and ask for application/json:

curl -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/events

A few important rules:

• Bearer auth only fires on JSON requests. Sending the same token on an HTML request (no Accept: application/json) is ignored — the token won’t authenticate a browser session.
• Tokens are global to the host. Admin lives on a single host (app.usetix.io); the token itself carries the account, so you don’t pass an account ID in the URL.
• Read tokens reject write methods. A POST/PATCH/DELETE with a read token returns 401 Unauthorized.

The scanner JSON endpoints also accept scanner device tokens paired from Settings → Scanner devices. Those tokens are scanner-only credentials for native door apps; they do not authenticate the broader account API.

Revoking a token

If a token is exposed or no longer needed, revoke it from Settings → API Tokens by clicking Revoke on the row. Revocation is immediate — the next request using that token returns 401 Unauthorized.

There’s no way to rotate a token in place. Generate a new one, update your integration, then revoke the old one.

Error responses

Status code	When you’ll see it
401 Unauthorized	Missing, malformed, invalid, or revoked token. Also returned when a read token attempts a non-GET/HEAD method.
404 Not Found	The resource exists in some account, but not yours. (We never reveal whether a record exists in another account.)

Token security at rest

Tokens are stored as plain values in our database with a unique index. We rely on the one-time reveal flow + revocation as the security boundary; there is no way to retrieve the raw token after the initial 10-second window. Hashed-at-rest storage is on the roadmap — when shipped, existing tokens continue to work.