How to rotate or revoke an API key

Before you start

Keys are listed under Customer API keys on the Integrations page, under Admin, then Settings, and owners and admins of a Pro Locker manage them. On a Locker without Pro, the page reads: Creating and rotating keys requires an active Pro plan. Existing keys are inactive while integrations are unavailable, and you can revoke them at any time.

A community can hold at most ten active keys, and every key expires after the number of days chosen when it was made, up to 90. If the community is near the ten-key limit, revoke a key for a connection you no longer use before you add another.

Rotate a key

When you rotate, the old and new keys both work until the overlap window you choose closes, so the other system can switch to the new key on its own schedule. When the window ends, the old key stops.

If you close the screen without copying the new key, Lockers cannot show it again. Rotate once more and copy it that time. Keep the key out of source control, URLs, logs, and anything that runs in a browser.

1. 1

   Find the key

   Open Admin, then Settings, then Integrations, and find the key under Customer API keys.

2. 2

   Select Rotate

   Select Rotate on that key's row.

3. 3

   Choose the overlap

   Choose how long the old key keeps working: Revoke old key immediately, 1 hour, 4 hours, 12 hours, or 24 hours.

4. 4

   Copy the new key

   Lockers shows the new key once. Copy it straight into a secret manager or an environment variable before you leave the screen. It starts with cs_live_.

5. 5

   Test it

   Paste it into the connected tool, then select Test the connection under Connection check to confirm the new key reaches your community.

Choosing the overlap

• Revoke old key immediately when the key may have leaked, or when you can paste the new one into the tool right away.
• 1 hour or 4 hours when you control the other system and will make the change today.
• 12 hours or 24 hours when someone else has to make the change, or the tool only picks up new settings on a release.

Revoke a key

Select Revoke on the key's row. Lockers asks you to confirm that the named key should be revoked immediately, and warns that requests using it will stop. Confirm, and requests that use that key fail from that point.

Revoke a key when you no longer need its connection, or when you believe the key has leaked. Revocation stays available after a Locker leaves Pro, so you can shut off an old key at any time.

What stops a key from working

Every request rechecks the key before answering, which is why a connection can stop without anyone touching the Integrations page. Four things end a key's access:

• The key reaches its expiry date. Keys last for the number of days set at creation, 90 at most.
• You revoke it, or rotate it and let the overlap run out.
• The admin who created the key loses admin access to the community. The integration stops with it.
• The Locker leaves Pro. Existing keys go inactive while integrations are unavailable.

Rotation keeps the connection and its attribution

Rotating changes the credential and leaves the connection itself in place. Drafts, invitations, and webhook endpoints created through that connection stay attributed to it, so a webhook endpoint bound to a named connection keeps delivering across the change.

Test the connection confirms the new key. It reports the connection's name, environment, permissions, restrictions, expiry, and quota windows, so one press tells you whether the new key works and what it can still do. To change what the key is allowed to reach, see Choose API permissions, and to set up a new connection, see Connect another tool to your Locker.