Authentication & Client Management

Understanding your credentials

When you create an API client, you work with three types of credential:

Credential	What it is	Lifetime	Visibility
Client ID	Unique identifier for the integration. Appears in audit logs.	Permanent (until client is deleted)	Always visible in admin UI
Client Secret	Shared secret used to prove identity when requesting a token. Reservie never stores the plaintext.	Permanent (until rotated)	Shown once only on creation or rotation
Access Token	Bearer token included in the `Authorization` header on every API call.	1 hour	Generated per request

Token expiry

Every access token expires after 1 hour. Your integration should:

Request a new token when the current one expires
Or proactively refresh before the expires_in time runs out
Handle 401 Unauthorized responses by requesting a new token

There is no refresh token mechanism — simply request a new token with your client ID and secret.

Client expiry

When creating a client, you can optionally set an expiry in days. After this date:

The client cannot obtain new tokens
The admin UI shows the client’s status accordingly
To restore access, create a new client

If no expiry is set, the client remains valid indefinitely (until suspended or deleted).

Secret rotation

If a secret is compromised or an integration partner changes, you can rotate the secret:

Go to Settings > API Clients
Click the action menu on the client
Select Rotate Secret

This immediately invalidates the old secret. A new secret is generated and shown once — copy it immediately. The client ID does not change. Existing tokens remain valid until they naturally expire (up to 1 hour).

Client lifecycle

API clients move through the following states:

Status	Can get tokens?	Description
Active	Yes	Normal operating state
Suspended	No	Temporarily disabled via admin UI. Can be re-activated. Existing tokens remain valid for up to 1 hour.
Expired	No	Past the expiry date set at creation time
Deleted	No	Permanently removed. Cannot be recovered.

Updating scopes

Scopes can be updated at any time via the admin UI without rotating the secret. The next token request will pick up the new scopes — existing tokens retain their original scopes until they expire.

Security best practices

Principle of least privilege

Grant only the scopes the integration actually needs. For example:

A reporting dashboard might only need customers:read and bookings:read
A CRM sync might need customers:read, profile:read, and profile:write
An attendance display might need events:read and events-register:read

Storing credentials securely

Never commit client secrets to source control
Use environment variables or a secrets manager
Rotate secrets if you suspect they have been exposed
Use separate API clients for separate integrations — if one is compromised, you can revoke it without affecting others