Authentication & Tokens
How to authenticate HeyTaco API requests and manage your tokens.
The HeyTaco API uses personal access tokens (PATs) to authenticate users and systems accessing data. You can create and manage tokens from Profile > API in the HeyTaco app. If you're a HeyTaco admin, you can manage tokens across your team, assign or revoke user scope access, and disable API access for your team from Admin API Settings.
To authenticate a request, send your token as a bearer token in the Authorization header:
Authorization: Bearer <your-token>Tokens
Tokens are user-owned, and resource access is defined via attached scopes. This means a few things:
- When a user is deactivated, so are their tokens. This prevents a former user from accessing team data after they leave a company.
- Token permissions are defined by the scopes attached to them, not by the role of the user who created them. That works in both directions: a developer who isn't a HeyTaco admin can create a token with elevated access once an admin approves the scope, and any token can be limited to only what its integration needs.
Before deactivating a user, check whether any of their tokens power active integrations. If they do, create a replacement token first so nothing breaks.
The token lifecycle
Creating tokens
Tokens are created from Profile > API. Any user can create a new token; the scopes you can attach are limited to those you have access to (see Scopes for how access works).
Editing tokens
Rename a token or change its scopes any time from Profile > API. Editing will not update the token's secret, so you won't have to update credentials anywhere. What it's allowed to do is another matter: scope changes take effect the moment you save. If you remove a scope that a live integration depends on, its next request will fail with insufficient_scope.
Rotating tokens
Rotating replaces a token's secret while keeping its name and scopes intact. From Profile > API, select "Rotate" on the token you'd like to rotate. HeyTaco will generate a new secret and keep the old one valid for a 7-day grace period, giving you time to add the new secret into your integration without downtime. After 7 days, the old token stops working.
Revoking tokens
Revoking a token invalidates it immediately. From Profile > API, select "Revoke" on the token you'd like to invalidate. Revocation is one-way; you can't un-revoke a token, so if you revoke one in active use, you'll need to create a new token (and update the integration) to restore access.
Token limits
Each HeyTaco team gets up to 25 tokens. Revoked tokens and rotated tokens still in their 7-day grace period don't count against this limit, so you're never blocked from creating a replacement when rotating or cleaning up.
Security
Only you 🫵 can prevent company data leaks. Keep your HeyTaco API tokens secret and secure.