---
title: Configuring API Keys
slug: zen-master/configuring-api-keys
docTags: 
createdAt: 2024-12-27T15:44:23.807Z
---

Using an API key and endpoint requests, you can integrate ZEN Master's streaming features into your applications.

ZEN Master Administrators can create API keys that control access to specific objects using ZEN Master Tags and Roles.

:::hint{type="info"}
Starting with the 18 Nov 2025 release, all ZEN Master API keys will have an expiration date:

- Existing API keys will expire on 18 Nov 2026.
- All new API keys will be set by default to expire one year after the creation date. You can set the expiration to an earlier date when needed.
:::



On the API Keys screen, you will see the following: 

- A list of existing API keys
- A **Documentation** link where you can download the latest ZEN Master OpenAPI file
- Admin users will see an **Add Key** button to create new API keys

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/-FGCgVMM3d5umCcW0Jf_n-20251119-172319.jpg)

The API Keys screen shows a list of API Keys available in the system.

- Click **Show** next to a key to show the string of characters for that key.
- Click **Copy** next to a key to copy the string of characters for that key.
- Click **Delete **next to a key to delete that key.

## To generate a new API key:

:::::WorkflowBlock
:::WorkflowBlockItem
In the main navigation, click **Configuration > API Keys**.
The **API Keys** screen is displayed.
:::

:::WorkflowBlockItem
Click + **Add Key**.
The **Create New API Key** screen appears:

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/OMSp-F7hpBdCoUXoIBDiy-20251119-172801.jpg)
:::

:::WorkflowBlockItem
In the **Name** field, enter a name for the new key using any alphanumeric characters.
:::

:::WorkflowBlockItem
If you wish to set the expiration date to less than one year, change the **Expiration Date**.
:::

::::WorkflowBlockItem
Check **Read only **to limit the use of the API key to GET methods. 

:::hint{type="warning"}
Check **Read only** to limit users to GET (only) all objects. 

Do NOT check **Read only** if you want to control user permissions by Role and Tag. 
:::
::::

::::WorkflowBlockItem
Check **Account Administrator **to allow API key users to read and write all objects, including account management objects (Users, User Groups, Roles).

:::hint{type="warning"}
Do NOT check **Account Administrator** if you want to control user permissions by Role and Tag. 

Account Administrator permissions override Role permissions.
:::
::::

::::WorkflowBlockItem
Check **Administrator** to allow API key users to read and write all objects, except for account management objects (Users, User Groups, Roles).

:::hint{type="warning"}
Do NOT check **Administrator** if you want to control user permissions by Role and Tag.

Administrator permissions override Role permissions.
:::
::::

:::WorkflowBlockItem
Select a **Role** - the role will work the same way as roles in the ZEN Master UI, giving the user to GET and/or create/edit Sources, Channels, Targets, etc. See [Adding Roles](docId:268Rk_Tt-vJbIwFUYl71S).
:::

:::WorkflowBlockItem
Click **Save**.
The new API key is added to the list of API keys.
:::

:::WorkflowBlockItem
You can view the new API Key by clicking **Show** next to the relevant key.
:::
:::::

## Control User Permissions by Role and Tag

Learn how to configure Roles and Tags to control user permissions for an API key. For details, see [Example: API keys with Roles and Tags](docId\:cYC8w6aCVnPbbl7z-lmTN).

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/wQdEAd9sMuX8e1pv4C4-o-20251119-173118.jpeg)

## Notes for using Roles with API keys

Setting a **Role** for the API key gives you granular control over which API requests the user will be able to make successfully. 

If the Role allows **viewing** a particular type of object (like **Sources**), the user will be able to make **GET** requests for that type of object. 

If the Role allows **editing** a particular type of object, then the user will be able to make **POST**, **PUT**, **PATCH**, and **DELETE** requests on objects of that type.

When the Role does **not** allow viewing objects of a certain type, **GET** requests on that type of object will return a `success: true` message, but with no results:

```json
{
    "success": true,
    "result": []
}
```

When the Role does **not** allow editing objects of a certain type, requests that attempt to create, update, or delete an object of that type will return a `success: false` message:

```json
{
    "success": false,
    "error": "Unauthorized: POST /api/v2/tags"
}
```

## Additional Notes

Here are some additional notes to keep in mind:

- Live Events are only available to Administrator-level users. So, permissions on Roles will not give access to Live Events
- Settings for Account Administrator, Administrator, and Read only take precedence over Roles permissions.
- Roles are cumulative. So, permissions apply for all Roles associated with an object.

## Known Issues

There are a few known issues around Roles:

- Live Events are only available to Administrator-level users. Even though you can select Role permissions for Live Events in the ZEN Master UI, they will be ignored.
- When a Role permission is set to read for an object, you will not be able to create, update, or delete the object. 
  - For create and delete, you will receive a Forbidden response.
  - For update, you will get a 200 response, but no fields will be updated.