Use authentication token APIs
The authentication token APIs let you generate, refresh, and revoke access tokens for the Zenoti API. Access tokens provide role-based authentication that respects the user's security permissions and expires after a set period.
For complete endpoint documentation including request/response schemas and code examples, see the individual API reference articles linked below.
Before you begin
- You need a backend application created in Zenoti with an App ID and App Secret. See Set up API authentication.
- Your security role must have the required permissions enabled.
Permission: Manage API Keys (under Administrator) -- Required to access Zenoti APIs.
Generate an access token
POST /v1/tokens
Generates a new access token for API authentication. Access tokens are valid for 24 hours.
| Parameter | Type | Required | Description |
|---|---|---|---|
| account_name | string | Yes | Your Zenoti organization account name as it appears in the Zenoti URL |
| user_name | string | Yes | The employee's username |
| password | string | Yes | The employee's password |
| grant_type | string | Yes | Must be password |
| app_id | string | Yes | The application ID from your backend application |
| app_secret | string | Yes | The application secret from your backend application |
| device_id | string | Yes | An identifier for the device making the request |
Response:
| Field | Type | Description |
|---|---|---|
| access_token | string | The token to include in API request headers |
| access_token_expiry | datetime | When the token expires (24 hours from generation) |
| refresh_token | string | Used to obtain a new access token without re-authenticating |
| refresh_token_expiry | datetime | When the refresh token expires (90 days) |
| token_type | string | Always bearer |
| token_id | guid | Unique identifier for this token |
| app_id | guid | The application that generated the token |
| user_type | string | Guest or Employee depending on the app configuration |
Refresh an access token
POST /v1/tokens
Generates a new access token using a refresh token. A refresh token can only be used once. Invoking this endpoint deactivates the existing access token and generates a new token pair.
| Parameter | Type | Required | Description |
|---|---|---|---|
| refresh_token | string | Yes | The refresh token from the original token generation |
| grant_type | string | Yes | Must be refresh_token |
Response: Same fields as the generate endpoint, with new token values.
Note: Refresh tokens are valid for 90 days. Using a refresh token before the access token expires renders both the old access token and refresh token invalid. Always use the latest token pair returned by this endpoint.
Revoke an access token
DELETE /v1/tokens/sessions/revoke
Immediately revokes all existing access tokens for the session. After revocation, the tokens cannot be used to access the API.
Include the access token in the Authorization: bearer {{access_token}} header. No request body is required.
Response: Returns null error on success, or an error object on failure (HTTP 400).
Tips
- Implement token refresh logic in your application to maintain uninterrupted API access. Refresh the token before it expires rather than waiting for a 401 error.
- Store tokens securely and never expose them in client-side code or log files.
- Revoke tokens when a user session ends or when you detect unauthorized access.