Set up API authentication
Authentication verifies the identity of the application or user making API calls to Zenoti. Zenoti supports two authentication methods: API key authentication for server-to-server integrations and token-based authentication for client-side applications with role-based access control.
On this page
- Before you begin
- Authentication methods compared
- Set up API key authentication
- Set up token-based authentication
- Security considerations
- Related articles
Before you begin
- You need administrator-level access to your Zenoti organization.
- Your security role must have the Manage API Keys, Manage Apps, and Manage Automation permissions enabled under Configuration > Security > Security roles > Permissions > Administrator**.
Permission: Manage API Keys, Manage Apps, and Manage Automation (under Administrator) -- Required to create backend applications and generate API keys.
Authentication methods compared
| Aspect | API key | Access token |
|---|---|---|
| Use case | Server-side integrations, global data access | Client-side applications, role-restricted access |
| Expiration | Valid for one year before renewal | Expires after 10 hours |
| Security level | Lower -- provides unrestricted access scope | Higher -- respects role-based permissions |
| Scope | Organization-wide (unrestricted) | Limited to the user's security role permissions |
| Header format | Authorization: apikey {{api_key}} |
Authorization: bearer {{access_token}} |
Set up API key authentication
Use API key authentication for server-to-server integrations where your backend application needs access to organization-wide data.
Steps
- Navigate to Admin > Organization > Backend Apps in Zenoti.
- Create a new backend application.
- Configure the required API group permissions for the application. These permissions control which API endpoints the application can access.
- Generate an API key for the application.
- Store the API key securely. Do not expose it in client-side code or public repositories.
To authenticate requests, include the API key in the Authorization header:
Authorization: apikey {{api_key}}
Note: API keys are valid for one year. Plan to renew your API key before it expires to avoid service interruptions.
Set up token-based authentication
Use token-based authentication for client-side applications where you need role-based access control.
Generate an access token
To generate an access token, send a POST request to the tokens endpoint.
POST /v1/tokens
| Parameter | Type | Required | Description |
|---|---|---|---|
| account_name | string | Yes | Your Zenoti organization account name |
| user_name | string | Yes | The user's login name |
| password | string | Yes | The user'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 | No | An identifier for the device making the request |
Response fields:
| Field | Type | Description |
|---|---|---|
| access_token | string | The token to include in API request headers |
| access_token_expiry | datetime | When the access token expires (10 hours from generation) |
| refresh_token | string | Token used to obtain a new access token without re-authenticating |
| refresh_token_expiry | datetime | When the refresh token expires |
| token_type | string | Always bearer |
| user_type | string | Guest or Employee |
To authenticate requests, include the access token in the Authorization header:
Authorization: bearer {{access_token}}
Refresh an access token
When an access token approaches expiration, use the refresh token to obtain a new access token without requiring the user to re-authenticate.
POST /v1/tokens
Include the refresh token in the request body to receive a new access token and refresh token pair.
Note: Using a refresh token before the access token expires renders the old access token and refresh token redundant. Always use the latest token pair.
Revoke an access token
To invalidate an active session, revoke the access token.
DELETE /v1/tokens/sessions/revoke
Include the access token in the Authorization header of the revocation request.
Security considerations
- Store credentials securely. Never expose API keys, App Secrets, or access tokens in client-side code, public repositories, or log files.
- Use token-based authentication for client-facing applications. Access tokens provide tighter security through role-based access and automatic expiration.
- Create separate backend applications for separate use cases. A single application with global permissions creates debugging difficulties and security risks.
- Monitor token expiration. Access tokens expire after 10 hours. Implement refresh token logic to maintain uninterrupted access.
- Renew API keys before expiration. API keys expire after one year. Set a reminder to renew before the expiration date.