> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Example

> Walk through a realistic RBAC example showing how to define roles, assign permissions to API keys, and verify access in your application.

Let's look at an example app for allowing your users to manage domains.

As part of the API, your users will be able to perform CRUD operations against domains or individual dns records.

<Steps>
  <Step titleSize="h2" title="Creating permissions">
    Users of our app can have the following permissions:

    * `domain.delete_domain`
    * `domain.dns.create_record`
    * `domain.dns.read_record`
    * `domain.dns.update_record`
    * `domain.dns.delete_record`
    * `domain.create_domain`
    * `domain.read_domain`
    * `domain.update_domain`

    Sign into your [dashboard](https://app.unkey.com). - For `Roles`, navigate to the `Authorization/Roles`. Default when navigating to `Authorization`. - For `Permissions`, navigate to the `Authorization/Permissions`.

    Create them in your `Authorization/Permissions` page. Use the button in the upper right. `+ Create new permission`

    <Frame>
      <img src="https://mintcdn.com/unkey/Trr_-IeanSW1JqU1/platform/apis/features/authorization/domains-permissions.png?fit=max&auto=format&n=Trr_-IeanSW1JqU1&q=85&s=ed58796ab4a67edb12bebab15bf2d31a" alt="Example permissions" width="3840" height="2160" data-path="platform/apis/features/authorization/domains-permissions.png" />
    </Frame>
  </Step>

  <Step titleSize="h2" title="Creating roles">
    We define the following roles:

    * `admin`: An admin can do everything.
    * `dns.manager`: Can create, read, update and delete dns records but not access the domain itself.
    * `read-only`: Can read domain or dns record information.

    Create them in your `Authorization/Roles` page. Use the button in the upper right. `+ Create new role`

    <Frame>
      <img src="https://mintcdn.com/unkey/Trr_-IeanSW1JqU1/platform/apis/features/authorization/domains-roles.png?fit=max&auto=format&n=Trr_-IeanSW1JqU1&q=85&s=aa6be7aa0ba9b0b3b73c62541b46eda4" alt="Example roles" width="3840" height="2160" data-path="platform/apis/features/authorization/domains-roles.png" />
    </Frame>
  </Step>

  <Step titleSize="h2" title="Connecting">
    For each role, we need to connect the permissions it should have.

    <Tabs>
      <Tab title="admin">
        <Frame>
          <img src="https://mintcdn.com/unkey/Trr_-IeanSW1JqU1/platform/apis/features/authorization/domains-roles-admin.png?fit=max&auto=format&n=Trr_-IeanSW1JqU1&q=85&s=35ba1e5faa3888789e9adec07a6a265b" alt="Admin roles" width="3840" height="2160" data-path="platform/apis/features/authorization/domains-roles-admin.png" />
        </Frame>
      </Tab>

      <Tab title="dns.manager">
        <Frame>
          <img src="https://mintcdn.com/unkey/Trr_-IeanSW1JqU1/platform/apis/features/authorization/domains-roles-dns.manager.png?fit=max&auto=format&n=Trr_-IeanSW1JqU1&q=85&s=ef34fa490f71905c119372659f406f69" alt="dns.manager roles" width="3840" height="2160" data-path="platform/apis/features/authorization/domains-roles-dns.manager.png" />
        </Frame>
      </Tab>

      <Tab title="read-only">
        <Frame>
          <img src="https://mintcdn.com/unkey/Trr_-IeanSW1JqU1/platform/apis/features/authorization/domains-roles-read-only.png?fit=max&auto=format&n=Trr_-IeanSW1JqU1&q=85&s=139acd200d2cb695e35bf3c220d83512" alt="read-only roles" width="3840" height="2160" data-path="platform/apis/features/authorization/domains-roles-read-only.png" />
        </Frame>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Connect a key">
    Now that we have permissions and roles in place, we can connect them to keys.

    <Tabs>
      <Tab title="Dashboard">
        1. In the sidebar, click on one of your keyspaces

        2. Next click on keys in the expanded keyspace you selected.

                   <Frame>
                     <img src="https://mintcdn.com/unkey/Trr_-IeanSW1JqU1/platform/apis/features/authorization/api-keys-navigation.png?fit=max&auto=format&n=Trr_-IeanSW1JqU1&q=85&s=41db76215cf893da1dd5935cadde4f7a" alt="Breadcrumb Navigation" width="3840" height="2160" data-path="platform/apis/features/authorization/api-keys-navigation.png" />
                   </Frame>

        3. On the key you want to use, click on the action menu (`...`) at the end of that table row.

        4. Select `Manage roles and permissions...`

        <Frame>
          <img src="https://mintcdn.com/unkey/Trr_-IeanSW1JqU1/platform/apis/features/authorization/api-key-screen.png?fit=max&auto=format&n=Trr_-IeanSW1JqU1&q=85&s=54945de959987bbce78c68f01dfeae2a" alt="Unconnected roles and permissions" width="3840" height="2160" data-path="platform/apis/features/authorization/api-key-screen.png" />
        </Frame>

        5. You can connect a role to your key by using the `Assign role` input. Let's give this key the `dns.manager` and `read-only` roles.

        <Frame>
          <img src="https://mintcdn.com/unkey/Trr_-IeanSW1JqU1/platform/apis/features/authorization/role-add-example.png?fit=max&auto=format&n=Trr_-IeanSW1JqU1&q=85&s=542803b28ef6479acf0ac76eeadc689f" alt="Unconnected roles and permissions" width="3840" height="2160" data-path="platform/apis/features/authorization/role-add-example.png" />
        </Frame>

        As you can see, the key now contains 2 `roles` and 5 `permissions` shown just above the Roles section:
      </Tab>

      <Tab title="API">
        You can attach roles to a key when creating it by providing the role names as an array:

        ```bash theme={"theme":"kanagawa-wave"}
        curl -XPOST \
          --url https://api.unkey.com/v2/keys.createKey \
          -H "Authorization: Bearer ${ROOT_KEY}" \
          -H "Content-Type: application/json" \
          -d '{
            "apiId": "${API_ID}",
            "roles": [
              "role1", "role2", "role3"
            ]
          }'
        ```

        See the [API reference](/api-reference/overview) for details.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verifying Permissions">
    Now you can verify this key and perform permission checks. [Read more](/platform/apis/features/authorization/verifying)
  </Step>
</Steps>
