ZenotiHelp

Set up API authentication

ZTZenoti Docs Team Updated August 21, 2026 3 min readGuide

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

  • 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

  1. Navigate to Admin > Organization > Backend Apps in Zenoti.
  2. Create a new backend application.
  3. Configure the required API group permissions for the application. These permissions control which API endpoints the application can access.
  4. Generate an API key for the application.
  5. 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.
Was this article helpful?
Your feedback helps us improve our documentation.