# Create, rotate, and revoke an API key

At the end, your own program calls the API with a key, with the permissions its purpose needs and an expiry date of your choice. The key is shown exactly once.

> **Type:** guide
> **For:** Anyone who issues or replaces access for a program of their own.
> **Prerequisite:** To issue and rotate keys, the permission **Create API keys**. To open the row menu and to revoke, **Revoke API keys**. To see other people’s keys, **List API keys**. Revoking depends neither on the package nor on the permission to issue. Existing keys keep working. Issuing or renewing keys is possible from the Premium package.
> **Where in the portal:** **Settings › Organization › API keys**, **Create key** button

## Steps

### Create a key

1. Open **Settings**, switch to the **Organization** tab, and open **API keys** there.
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](#options-the-six-classes)) 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.

![The Create API key dialog with the name field and its placeholder (1), the six permission classes (2), the Adjust individual permissions row with the number of included permissions (3), the lifetime under Valid until (4), the period under Old key valid until (5), and the Create button (6)](/docs/developers/bilder/7483b850-create-api-key-dialog.png)

### 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.”

| Class | What it allows |
|---|---|
| **Read only** | Fetch content, media and schedules — change nothing. |
| **Media automation** | Upload media and manage folders. |
| **Content authoring** | Create and change scenes and templates. |
| **Playout control** | Manage playlists and schedules. |
| **Full access** | Everything your account may do through the API. |
| **Custom** | Individual permissions, each explained. |

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 **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**.

![The list of API keys with the Create key button (1), the columns Name / permissions, Class, Created by, Created, Valid until, and Last used (2), the class with the suffix adjusted (3), and the open row menu with Rotate and Revoke (4)](/docs/developers/bilder/e000f3d6-api-key-list.png)

## If something goes wrong

| Symptom | Meaning | Solution |
|---|---|---|
| **Create failed** | The key was not issued. | Click again. If it persists, deselect a permission that your own account does not have. |
| **Rotation failed** or **Revoke failed** | The previous state remains unchanged: no successor, no revocation. | Run the action again. |
| The key is lost. | It is never shown a second time. | **Rotate**, or create a new key and revoke the old one. |
| A program is suddenly rejected although the key is valid. | The account that created it is suspended. The key is dormant. | Have the suspension lifted, or create a new key from an active account. |

## Related

- [What can your own programs do with Szenera?](/docs/developers/about-integrations)
- [Permissions by role and by area](/docs/organization/permissions-by-role)
- [Read and export the change log](/docs/organization/read-change-log)