Generating and revoking an API key

⚠️ Prerequisite: the public API option must be open on the account. No back-office screen switches it on: your Beedeez contact opens it. Without it, the Developers API entry does not appear in the menu.

⚠️ Rights needed: the Update customization right, which is the one that opens the Configuration menu. There is no dedicated right for API keys, and this right cannot be granted to a profile attached to a department.

An API key is not what authenticates your calls. You exchange it once for an access token, in the appSecret field of POST /v1/token, and that token authenticates every following call. This article covers where the key is generated, how to store it, and how to have it deleted. The calls the key opens are described in the OpenAPI reference, at doc.developers.beedeez.com .

Generating a key

Open the gear icon, then Configuration › Integrations › Developers API. Follow these two steps in this order:

1. Move the toggle from Disabled to Enabled, then click Save all at the bottom of the left column. The generate button stays hidden until the activation is saved.
2. Click Generate Secret Key. The value appears in the field to the right of the button, as 64 hexadecimal characters. Before you generate, that field contains a row of tildes, which is not a key.

Storing the key before you leave the page

⚠️ The screen warns you above the button: “The Secret Key can be viewed only once. Please copy it and keep it.” This warning is accurate.

Copy Secret Key places the value on the clipboard and clears the field in the same action. Reloading the page also loses it. After that, no back-office screen and no public API call displays it again. If you did not store it, consider it lost and generate another one.

Paste the key into your secret store immediately, before leaving the page. Do not put it in an email, a ticket or a chat channel. A key works like a password: on its own, it opens the account’s data.

What the screen does not provide

• No name and no label. There is no field to fill in, so nothing distinguishes two keys. Keep your own list: generation date and destination.
• No listing. The screen shows neither the existing keys, nor how many exist, nor when each one was last used.
• No expiry. A key stays valid indefinitely until it is deleted.
• No scope selection. Every key grants full administrator access to the account’s data, with no perimeter selector and no read-only mode. A key generated from inside a department still opens the whole account.
• No revoke button.
• No link to a person. A key belongs to the account. Deactivating the administrator who created it does not stop it working.

Behaviour to anticipate

⚠️ Setting the toggle back to Disabled revokes nothing. It only prevents new keys from being generated. Keys already issued keep working, and the API keeps answering them.

⚠️ Generating a key does not replace the previous one. Each press adds a key, and all of them stay valid alongside each other, including those you no longer track.

Each key carries its own refresh token. Exchanging one key for a token invalidates only the refresh token previously issued for that same key, so two integrations holding two different keys do not log each other out. Two integrations sharing a single key do: the second exchange consumes the refresh token the first one held.

💡 Tip: give each integration its own key. You then keep the ability to have one deleted without interrupting the others.

Revoking a key

No action is available from the back-office. Ask your Beedeez contact to delete the key, naming the account and the key concerned.

Deletion stops new tokens being issued as soon as it is applied, but an access token already issued is not cancelled and stays valid for up to 6 hours after it was created. Count that delay before you treat the access as closed. Report a leaked key as a security incident rather than waiting for the expiry.

Replacing a key

Because a key cannot be deleted from the back-office, plan the replacement in this order:

1. Generate the new key and store it safely.
2. Deploy the new key in the integration that uses the old one.
3. Check that calls go through with the new key.
4. Ask your Beedeez contact to delete the old key.

Ask for the deletion last. In the reverse order, you have nothing to fall back on if the deployment fails.

Going further

• Authenticating on the API: what you do with the key once you have it, and the most common integration mistakes.
• Available resources: what the API actually exposes, to read before you size a development.
• API, webhooks, callbacks: which to choose: check that an existing connector does not already cover the need.
• Assigning rights: granting Update customization to the right person.