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. (V1 is read-only — write endpoints arrive in a future release.)
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.

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.