Skip to main content

Rotate or revoke an API key

An API key lets a script, a CI job or an agent call Jaah as you. Rotate a key to give it a new secret while keeping its name, permissions and expiry, for example on a schedule or when someone who saw it leaves. Revoke a key when it has leaked or nothing uses it any more: every call with it is refused from then on.

Who can do this: every member, for their own keys. Only a key's owner can rotate it. An Org Owner or Org Admin sees every key in the organization and can revoke any of them, but never sees a secret.

Rotate a key​

  1. Open your keys: select your initials at the bottom of the sidebar, then My Profile, then Security. Your keys are under API keys.

    Settings › API keys: New key above the list, with a revoked key's row and its ⋯ menu

  2. Select the key's row. Its page opens on Overview, with Rotate and Revoke at the top. If the page reads "owner's key. Only its owner can change or rotate it.", the key belongs to someone else: ask them, or revoke it as below.

  3. Select Rotate. The Rotate name? dialog says a new secret replaces the current one, and that settings and expiry stay the same.

  4. In Old secret keeps working for, pick how long calls with the old secret still succeed: None (the old secret stops at once), 1 hour, 24 hours (the default) or 7 days. Pick None if the old secret leaked.

  5. Select Rotate. The new secret shows once, with "Copy it now. You won't see this secret again." Select Copy secret, store it where the script or job reads it, then select Done.

  6. Check Overview: Old secret says until when the previous secret still works. Replace it everywhere before then. Last used shows when the key last made a call and from which address.

Rotating never moves the key's expiry. For a key about to expire, make a new one instead; see Replace an API key before it expires.

Revoke a key​

  1. Open the list of keys as in step 1 above.
  2. Select ⋯ on the key's row, then Revoke. You can also open the key and select Revoke at the top of its page.
  3. The Revoke name? dialog says every call with the key is refused from now on, and that this can't be undone. Select Revoke.
  4. The key stays in the list, dimmed and marked Revoked. Its page reads This key has ended. Create a new one. To give the script or job access again, select New key and make a new key.

The key's Activity tab lists its rotation or revocation, with who did it. The same events are in Audit, where a call made with a key reads "owner via API key name".