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

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.

Automation OAuth

Registered Zapier, Make and n8n clients use the same account JSON API with OAuth access tokens. Authorization uses /oauth/authorize, the authorization-code exchange and refresh use /oauth/token, and the resource is https://app.usetix.io/admin. Public clients require PKCE (S256); native connectors use PKCE as well. Access tokens expire after one hour.

Scopes are api:read, api:write, and webhooks:write. api:read is required; webhooks:write can manage that connection’s subscriptions without allowing business writes. Every request still requires Accept: application/json.

The approving user selects one account. Their current role and event assignments apply on every request and delivery. OAuth tokens cannot create API tokens or inspect another connection’s subscriptions. Revoke connections under Settings → API Tokens → Automations. Providers can disconnect their own connection with DELETE /admin/automation_connection; this revokes its tokens, refresh tokens, pending grants and subscriptions.

GET /admin/identity returns { "id": "…", "name": "…", "subdomain": "…", "role": "…", "webhook_actions": ["order.paid", "…"] }. Use it to verify credentials and label the connected account. OAuth access and refresh tokens are stored as hashes; this differs from the existing manually generated API tokens.

Idempotent creates

POST /admin/events, /admin/promo_codes, /admin/webhooks, and /admin/events/:slug/guest_parties accept an optional Idempotency-Key header on authenticated JSON requests. Use a stable source record or notification ID. Keys contain 1–200 ASCII letters, digits, dots, colons, underscores or hyphens.

An identical successful request returns the original status, JSON and Location, with Idempotency-Replayed: true, for seven days. Reusing a key with a different method, URL, body or access scope returns 409. Validation failures do not consume the key. Keys are isolated by account and credential/connection; revoked credentials cannot retrieve a cached result. Creation and the response receipt commit in the same transaction. The temporary receipt stores the response JSON and is removed after seven days.