Skip to main content

Community API Keys

Create, use, replace and revoke the API keys your own systems use to call the Gradual API.

Community API keys authenticate requests to Gradual's Public API. Each key belongs to your community, not to a person, and carries its own access level and expiry. Community admins create and manage keys in the dashboard under Settings → API Keys. Other dashboard roles cannot see the page or the key data.

Creating a key

  1. Select Create API Key. In the Create API key panel, give the key a Name. Names are required, can be up to 60 characters, and must be unique within your community — names are compared without regard to capitalisation, and the name of a revoked key cannot be reused.

  2. Choose the key's Access level:

    • Read-only — the key can read data but every write is refused. This is the default.

    • Read & write — the key can read and change data.

    • A key with Read & write access can also be allowed to erase members for GDPR requests. Select Allow member deletion (GDPR erase), which appears only once Read & write is selected and is cleared by default. It lets the key erase members permanently, so give it only to an integration that needs to action erasure requests.

  3. Set when the key should stop working. The Expires list offers fixed periods and shows the date each one works out to; it defaults to In a year.

  4. Select Save to create the key.

If the key is allowed to erase members, Gradual asks you to confirm before it is created. The message explains that turning on GDPR erase lets any integration using the key delete members and their personal data through the API. Tick I understand this key can permanently erase member data — until you do, Create Key stays unavailable — and then select Create Key.

The key is shown once

When the key is created, an API Key created dialog shows the complete key once, with a copy button, above a reminder that it will only be shown once. Below it, the dialog repeats the key's access and expiry date.

Copy the key and store it somewhere safe, such as a secret manager, before you close the dialog. You have to tick I've stored this key somewhere safe, such as a secret manager. before Done becomes available. Afterwards the dashboard only ever shows a masked version of the key, and the full value cannot be recovered. If you lose it, replace the key.

Using a key

Send the key as a bearer token in the Authorization header of your request. A request with no key, a malformed header or an unknown key is rejected as unauthorised; a request the key's access level does not allow is rejected as forbidden. Responses carry rate-limit headers so your integration can pace itself.

The API Keys page

Each key is listed with its name, a masked version of the key itself, its access, who created it, when it was created, when it expires, when it was last used, and its status — Active, Expires soon or Expired. You can narrow the list by name, access or status.


The API Keys page, listing one key with its masked value, access level, creation and expiry dates, last use and status.

A key with permission to erase members carries a GDPR Erase badge beside its access level.

Keys created in the dashboard begin with gdl_key_. A key issued for your community before self-serve key management was available may have a different form; it is listed and managed in the same way.

When a key is approaching its expiry date, the page shows a banner naming the key and the date, so you can create a replacement and move your integration across before the key stops working.

The page also shows when each key was last used, so you can tell which keys are still in service before you revoke one.

Replacing and revoking a key

  1. Open the action menu at the end of the key's row.

  2. Replace creates a new key that carries the same settings as the old one. The old key keeps working until you revoke it, so you can move your integration across without an outage.

  3. Revoke stops a key immediately — any request made with it afterwards is rejected. Revoked keys stay listed so that past changes can still be attributed to them, and the name of a revoked key cannot be reused.

What the Audit Log records

Creating and revoking a key is recorded in the Audit Log with the admin who did it and the key's name. Changes made through the API, including GDPR member deletions, are attributed to the key that made them.

Email notifications

The address set as Admin Notification Recipient (Settings → System Settings → Email Settings) is notified when a key is created, before a key expires, and when a key has expired. Keys that were revoked, and keys that expired some time ago, are not included. If the admin who created the key has been archived or is no longer a Community admin, the notification goes to the Admin Notification Recipient instead.

Did this answer your question?