API keys and external system access

The "API keys" screen is the actual place where you manage API access for external systems.

When to use this page

• when a CRM, website, mobile app, or another external system needs API access to your data;
• when you want to give different access levels to different external systems;
• when you need to stop, limit, or remove existing API access.

Access

1. Open Integrations.
2. Select "API keys".

What you see in the list

• "Name"
• "Expires at" (or "Never")
• "Last used" — when an external system last used the key (or "Never" if it has not used it yet)
• "Active"
• Actions: "Edit API key", "Generate new key", "Delete API key"

Create a new key

1. Select "New API Key".
2. Fill in "Name" (required), "Expires at" (optional), "Active", and "Select permissions".
3. Select "Create".
4. Securely store the displayed token and provide it to the external system.

What each field means

• "Name" is your internal label for the key.
• "Expires at" defines when the key should stop working. If left empty, the key has no expiration.
• "Active" lets you stop or allow access without deleting the key.
• "Select permissions" defines which resources and actions will be available through this key.

How permissions work

• Permissions are selected separately for each key.
• The key can access only the resources and actions you have allowed.
• Each permission carries a short description of what it allows.
• If access should be more limited, create a separate key with fewer permissions.

Permissions that change your calendar

Three permissions let the external system change appointments that already exist. Each one carries a short description on the screen — what follows is the consequences that do not fit there:

• "Reschedule appointments" works for single appointments only. Group appointments, and appointments that have already started or passed, are refused. Scheduled reminders move to the new time, but the client does not automatically get an "appointment changed" notification — in the Business app that is a separate choice when saving, and the API offers no such choice.
• "Change participant status (cancel / no-show)" applies to the individual person, not to the whole group. It can set any of your business's statuses, including your own custom ones — not only the three in the permission name. Cancelling in a group automatically promotes a client from the waiting list into the freed seat.
• "Delete appointments" removes the appointment from the calendar entirely.

warning

Grant these only to a system you trust to manage your calendar. A deleted appointment cannot be restored from the Business app. For a cancellation that stays visible in the history, use the participant status permission instead of deletion.

Changing the number of seats in a group appointment is not available through the API.

Permissions for client data

• "View clients list" allows searching your entire client list — by phone, email, external number or part of a name.
• "View client" opens an individual client profile.
• "Create client" lets the external system write new client profiles into your business.
• "Edit client" lets it change the data of an existing profile.

warning

"Create client" always creates a new profile — the external system does not look for a match and does not merge with an existing client. If the integration sends the same person twice, you end up with two profiles. The external system must therefore check whether the client already exists first, usually by external number. Email is not a reliable key — one business may hold two profiles with the same email address.

Clients created this way count towards your subscription's client limit exactly like the ones you create by hand.

warning

The appointment permissions also expose client data. A key holding only "View appointments list" sees the clients on those appointments, without you having granted it the client permissions.

Phone and email are shown partially masked everywhere. Full contact details are revealed only if you also grant "View sensitive information" from the "Clients" group.

This is a decision about your clients' personal data, not a technical detail.

Permissions for memberships

Two permissions let the external system read memberships without being able to change them:

• "View issued memberships" shows the memberships issued to clients and what is left on them;
• "View issued membership" opens the details of one issued membership.

This is useful when the external system needs to check whether a visit is already covered by a membership before it books an appointment.

Both permissions work only if the business has memberships included in its subscription plan. If memberships are not included, the request is refused rather than returning an empty list — so the difference between "nothing issued" and "memberships are not in your plan" stays visible.

Memberships cannot be issued, changed or cancelled through the API.

Notifications and wallet

Actions performed through the API send the client the same notifications that the same actions send from the Business app, according to your settings for channels and notification types — deletion included.

One exception: rescheduling sends no automatic "appointment changed" notification (see above).

Paid channels (SMS, Viber) draw from the business wallet. When the balance runs out the channel is skipped and the notification is not sent through it.

How to manage an existing key

• use "Edit API key" when you need to change the name, expiration, status, or permissions;
• turn off "Active" if you want to stop access temporarily;
• use "Generate new key" when the token is lost or has reached someone who should not have it;
• use "Delete API key" if the integration no longer needs access.

warning

For keys created before the separate availability permission was introduced, the checkbox is already ticked. Unticking it stops the external system from receiving available slots and breaks the integration.

In the key's window, in the "Access key" section, you see:

• "Ends in" and the last four characters of the token — so you can tell your keys apart without the token being shown again;
• "Last used" — when an external system last sent a request with this key. A refused request counts too, for example while the key is turned off: it still shows that the external system is using the key. The value updates at most once every 5 minutes.

Generate a new key

The key keeps its name, permissions, status and expiration — only the token changes. The staff member who generates the new key needs the "Edit API keys" permission from the "API keys" group.

1. Open Integrations → "API keys".
2. Select "Generate new key" from the key's menu in the list or from the "Access key" section in the key's window.
3. In the "Generate a new key?" window, confirm with "Generate new key".
4. Copy the new token from the "API Access token" window and paste it into the external system.
5. Select "I understand, close".

The old token stops working as soon as you confirm. Until you put the new one into the external system, it has no access to your data. Once the external system starts using the new token, the time appears under "Last used" — until then it reads "Never".

tip

If the integration must not stop even for a minute, create a second key with the same permissions, put it into the external system, and only then delete the old one.

How API access works

This section is for the person who sets up the external system.

• The external system sends the token in the Authorization HTTP header as Bearer <token>. Tokens start with rsk_. There is no other way — a token in the request URL or in another header is not accepted.
• Access depends on the key being active, not expired, and having the required permissions.
• The business must also have the external_connectivity feature active in its subscription.

When the key cannot be used, the response is 401 with a reason:

Message	What it means
API key is not active.	the key is turned off with "Active"
API key is expired.	the date in "Expires at" has passed
The access key is unknown or has been replaced.	there is no such token: the key was deleted, a new key was generated in its place, or the token is mistyped
Unauthenticated.	the token is missing or is not a valid API key token

What is available in the current product

• JSON:API v2 supports API key access.
• The public v2 specification documents resources such as services, available slots, appointments (viewing, creating, cancelling, rescheduling, and deleting), clients (lookup by phone, email, external number or part of a name, plus creating and updating), issued memberships and membership plans (read only), working hours, installments, and payments.
• If external_connectivity is not active, some requests can return 402 Payment Required.

Critical security note

• After creation and after "Generate new key", the system shows "API Access token" in a separate window.
• This token is shown once only. After closing, it cannot be shown again — if you lose it, generate a new key.
• Store the token securely and do not share it.

What is not available in the current UI

• "Logs" is present in the menu but currently disabled in the UI.
• The token is not shown when you edit a key. If you need it, generate a new key.
• There is no dedicated webhook setup screen in the Business UI.

Related topics

• Integrations and API
• Google calendar