API keys, connected apps and API usage

API keys are part of Cliedesk Pro. Other systems, such as your billing tool or a script on your server, use a key to work with Cliedesk through the Public API. People with the Manage API credentials permission (Admins) manage keys in Settings → Developer → API keys.

A key never does more than its owner may. If the owner cannot see a product, the key cannot see it either.

Create a key

1. Select Create key and give the key a name, for example “Billing sync”.
2. Choose the Type:
   • Live reads and changes real data.
   • Test reads real data, but changes are only checked or simulated. Nothing is saved or sent. Use it while you build an integration.
3. Choose the Scopes: what the key may do. Start with Read only and add only what the system needs.
4. Optional: in Allowed IP addresses, enter one address or range per line (for example 198.51.100.0/24). The key then works only from these addresses.
5. Choose when the key Expires (after 365 days by default). Never shows a warning. Tick the box to confirm it.
6. Select Create key. Copy the key now and store it in a safe place. It is shown only once.

The key list

The list shows each key with its owner, scopes, last use and expiry.

• Unused: the key was not used for 90 days. Revoke it if nothing needs it.
• Seen in a URL, replace it: the key was sent in a web address, where it can end up in logs. Create a new key and revoke this one.

To stop a key at once, select Revoke. Systems that use it get an error from the next request on. You can always create a new key here or with wp cliedesk api key create.

Personal API keys

Team members can make their own keys in My API keys (see AI permissions). Under Personal API keys on this screen you set two limits, then select Save limits:

• Share of the site key limit (%): how many of the site’s 100 active keys personal keys may use. From 0 to 50; 30 by default. 0 stops new personal keys.
• Longest life (days): personal keys always expire, at the latest after this many days. From 1 to 365; 365 by default.

Apps that connect as you (OAuth)

Some apps, such as AI assistants, connect to Cliedesk as a person instead of with a key. The app opens a Cliedesk page that asks Connect … to Cliedesk?. It shows the app name, the address you go back to and what the app may do. Untick what the app should not do, then select Allow or Deny. The app never gets more rights than you have.

• Settings → Team → Connected apps lists the apps you allowed. Select Disconnect to end an app’s access.
• Admins see every app in Settings → Developer → OAuth apps. There they can Block or Remove an app, end a person’s connection, and turn off Apps may register themselves (on by default, at most 200 apps).

API usage

Settings → Developer → API usage (permission Manage integrations) shows the requests of the last day, 7 days or 30 days:

• the number of requests, errors and rate-limited requests;
• an alert when a key used 80 % or 90 % of its limit per minute;
• the keys with the most requests, and the requests per key and endpoint.

Each key may use 600 units per minute and make 120 changes per minute (defaults). Heavier requests cost more units. When a key reaches its limit, it gets the answer “429 Too many requests” and waits until the minute is over. If a key often reaches its limit, let the system receive webhooks instead of asking again and again.