---
title: Example: API keys with Roles and Tags
slug: zen-master/example-api-keys-with-roles-and-tags
docTags: 
createdAt: 2025-11-17T20:36:16.308Z
---

## Control User Permissions with Roles and Tags

In this example, we'll create an API key that allows read-only access privileges to a specific group of Sources.

### Step 1: Create a Tag

First, we'll create a Tag that can be assigned to ZEN Master objects.

::::WorkflowBlock
:::WorkflowBlockItem
In the left navigation, select **Configuration** > **Tags**.

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/bZgiqXMpFTqSXDJcDdrHk_image.png)
:::

:::WorkflowBlockItem
Select **+Add** to create a new Tag.

::Image[]{src="https://app.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/yDZjd_QUCy4EXyrjp8xbc_image.png" size="50" width="370" height="104" position="center" showCaption="false"}
:::

:::WorkflowBlockItem
Give the Tag a name and select **Save**.

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/VRUWf7KOb-hsAg9xRMM9B_image.png)
:::
::::

### Step 2: Create an API key

Next, we'll create an API key.

:::::WorkflowBlock
:::WorkflowBlockItem
In the left navigation, select **Configuration** > **API Keys**.

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/PXW3-E2NHobqvbgamviRy_image.png)
:::

:::WorkflowBlockItem
Select **+Add Key** to create a new API key.
:::

::::WorkflowBlockItem
In the **Create New API Key** page: 

- Enter a name for the API key.
- Set the expiration date or leave the default.
- Leave the other options unchecked/unselected.

:::hint{type="info"}
Since the **Read only**, **Account Administrator**, and **Administrator** options override the Roles persmissions, leave them unchecked.
:::

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/gUqA9aQRbKthZ9WKdfOk1_image.png)
::::

:::WorkflowBlockItem
Click **Save** to create the API key.
:::
:::::

### Step 3: Create a Role

With a Role, we can select user permissions for object types.

::::WorkflowBlock
:::WorkflowBlockItem
In the left navigation, select **Account Management** > **Roles**.

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/MMkjXew3wYjCjgJNoMQqe_image.png)
:::

:::WorkflowBlockItem
Select **+Add** to create a new Role.
:::

:::WorkflowBlockItem
In the **Create New Role** page: 

- Enter a name for the Role.
- Select the Tag that we created in Step 1.
- For **Permissions**, select the checkbox for Source.
- Select the API key that we created in Step 2.

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/mqtABnEtKNlklVyg2Ua5j_image.png)
:::

:::WorkflowBlockItem
Click **Save** to create the Role.
:::
::::

### Step 4: Add Tag to Sources

Now, we can add our Tag to the Sources that we want to give read access to for our API key.

::::WorkflowBlock
:::WorkflowBlockItem
In the left navigation, select **Sources**.
:::

:::WorkflowBlockItem
Select the Sources that you want to grant read access for the API key, and click **Edit**.

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/1FIpCTnpeHHIc5QLmoLup_image.png)
:::

:::WorkflowBlockItem
In the **Edit Sources** page:

- Select the checkbox to update Tags.
- Select Add to add our new Tag without overwriting or removing any existing Tags.
- From the dropdown menu, select our new Tag.

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/BD92gWX546-67yBF-WqLv_image.png)
:::

:::WorkflowBlockItem
Click Save. The multi-edit dialog should confirm that each selected Source has been updated.

![](https://api.archbee.com/api/optimize/mzxtTQEvCNIdUNgF2kuwJ/KFLYtRqmFdZ6z29AHKsI5_image.png)
:::
::::

### Step 5: Using the API key

Let's test our API key persmissions by making a request to the ZEN Master API.

The new API key grants the API Caller read permission only for the Sources that share the key's assigned Tag and Role.

::::WorkflowBlock
:::WorkflowBlockItem
Send a GET API request to list all Sources.

```curl
curl --location 'https://api.zen.zixi.com/v2/sources' \
--header 'x-api-key: <your api key>' \
--header 'Accept: application/json'
```
:::

:::WorkflowBlockItem
The API response should only contain the two Sources that we tagged.

```javascript
{
    "success": true,
    "result": [
        {
            "id": 12345,
            "name": "api_docs_zixi_other_push",
          ...
        },
        {
            "id": 12346,
            "name": "api_docs_zixi_other_push_api",
          ...
        }
    ]
}
```
:::

:::WorkflowBlockItem
Since we only have read access to two Sources, we will not be able to read other objects. Send a GET API request to list all ZECs.

```curl
curl --location 'https://api.zen.zixi.com/v2/zecs' \
--header 'x-api-key: <your api key>' \
--header 'Accept: application/json'
```
:::

:::WorkflowBlockItem
The API response will be **200 OK**, but the result will be empty.

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

:::WorkflowBlockItem
With only read access, we will **not** be able to **create**, **update**, or **delete** any objects. Send a POST API request to create a new Source.

```curl
curl --location 'https://api.zen.zixi.com/v2/sources' \
--header 'x-api-key: <your api key>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "name": "api_docs_zixi_other_push",
  "broadcaster_cluster_id": 4444,
  "target_broadcaster_id": -1,
  "resource_tag_ids": [
    11
  ],
  "autopull_latency": 1000
}'
```
:::

:::WorkflowBlockItem
The API response will be an Unauthorized error.

```javascript
{
    "success": false,
    "error": "Unauthorized"
}
```
:::
::::