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

Account owners manage account-wide tokens at Settings → API Tokens. Managers cannot create account-wide tokens. External co-organizers manage their own personal tokens through API Tokens in the sidebar.

Personal tokens are bound to the co-organizer’s team membership. They can access only currently assigned events and the actions allowed for that role. write adds permission to make allowed changes; it does not grant account-wide rights. Removing an event assignment takes effect on the next request. Deactivating the membership or changing its role invalidates its personal tokens, including when promoting the person to manager. A shared owner token retains its account-wide permissions.

Co-organizers can use personal tokens for historical and live analytics and to manage their own webhooks. Account settings, refunds, team administration, scanner access, and other members’ integrations remain unavailable.

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 use its read or write permissions within its account and event access scope. 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, open API Tokens (under Settings for account owners) and click Revoke on its 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.
403 Forbidden	The token’s role cannot use this action, such as team administration with a personal co-organizer token.
404 Not Found	The resource is missing or outside the token’s account, assigned events, or personal integration scope.

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.