Create, rotate, and revoke an API key

An API key lets your own program use the Szenera API, with exactly the permissions it needs and an expiry date you choose. The key is shown only once, so copy it right away.

Steps#

Create a key#

1. Open Settings, expand For developers at the bottom of the sidebar, and choose API keys.
2. Click Create key. The Create API key dialog tells you up front: “Set a name and permissions. The plaintext key is shown exactly once afterwards.”
3. Under Name, enter what the key is for. The placeholder reads Name (e.g. CI import).
4. Under Permissions, choose one of the six classes (see Options) or adjust the permissions individually.
5. Choose Valid until: In 30 days, In 90 days, In one year, or No expiry. The hint for it: “An expiry date limits the risk.”
6. Under Old key valid until, choose how long the old key stays valid alongside its successor after a later rotation: Invalid immediately, 1 hour, 24 hours, or 3 days. The default is 24 hours.
7. Click Create.
8. The key now appears under API key — visible only now. Click Copy key, store it safely, and close with Got it. Only its fingerprint is saved.

Rotate a key#

Rotating replaces a key without downtime: the successor is created immediately, and the old key stays valid for a set period.

1. In the key’s row, open the three-dot menu at the right edge and click Rotate. The Rotate key dialog announces a successor with the same permissions. It is also shown only once.
2. The dialog asks: “How long should the old key stay valid alongside it? Use that window to switch your systems over.” Click Invalid immediately, 1 hour, 24 hours, or 3 days. Your choice triggers the rotation.
3. Copy the successor as you did when creating. The message Key rotated — the old one stays valid until … shows when the period ends.

Revoke a key#

1. In the row, open the three-dot menu at the right edge and click Revoke.
2. Confirm the Revoke key? prompt. It names the key and the consequence: invalid immediately, running integrations lose access.

No grace period, no way back, and no package standing in the way. Closing a hole is always possible.

Options: the six classes#

The class defines which permissions a key gets. It is chosen for each key and never inherited from the account: “Chosen from the permission catalog — a key can never do more than you may.”

Each class states its scope as a number, such as 12 permissions. Custom shows free choice instead. With Adjust individual permissions you add or remove permissions. Next to it, the dialog shows the current selection as a sentence, such as Includes 12 permissions., with the number of your selection. The list then appends the suffix adjusted to the class, for example Read only, adjusted. The origin stays visible.

Check the result#

The list shows Name / permissions, Class, Created by, Created, Valid until, and Last used. Created by shows You or Deleted account, and Last used initially shows Never used. A timestamp there proves the connection. It is updated at most once per minute.

A key acts with the permissions of the account that created it. If that account is suspended, the key stays dormant until the suspension is lifted. If the account is deleted, the key is revoked.

Without the permission List API keys, you see only your own keys: “Other members’ keys are reserved for accounts with administrative rights.”

Every creation, rotation, and revocation appears in the Settings › Organization › Change log. When your application later calls something, the Triggered by column shows the key’s name. The detail view shows the value API key under Kind.

If something goes wrong#

Related#

• What can your own programs do with Szenera?
• Roles and permissions
• Read and export the change log