# Access Role Concept

## Overview

This guide aims to give an overview to the access roles for Unique.

The access role concept has four layers: Zitadel Roles, Unique Roles, Space Access and Scope Access.

- **Zitadel Roles** can modify settings and entities on Zitadel itself. That means they can manage organisations, users, branding and all other information of the Zitadel itself.

- **Unique Roles** determine the access to the application and specific features in the application.

- **Space Access** determines to which space which user or user group has access.

- **Scope Access** determines which user or user groups can read (see) or write (add/modify) documents to which scopes (folder). Based on this configuration, you define what knowledge the user has access to when using spaces.

**Zitadel Roles** and **Unique Roles** are managed via **Zitadel**.

**Space Access** and **Scope Access** are managed in the **Unique App** or via APIs.

## 1. Zitadel Roles

Zitadel Roles can modify settings and entities on Zitadel itself. That means they can manage organisations, users, branding and all other information of the Zitadel itself and are provided through Zitadel, following this documentation: [Zitadel Managers Documentation](https://zitadel.com/docs/guides/manage/console/managers)

Some typical roles we use at Unique are :

| **Role Name**             | **Remarks**                                                                                               |
|---------------------------|-----------------------------------------------------------------------------------------------------------|
| IAM_OWNER                 | Only assigned to 2 users, that are able to manage the Instance.                                          |
| IAM_OWNER_VIEWER          | Can view everything on the Instance (but not edit). Used for `scope-management` service user.           |
| IAM_ORG_MANAGER           | We can have multiple that can make changes on the organisation level, including but not restricted to Managing Users and their authorizations. |

Other roles might be relevant for service users.

Can be adapted to meet the Customer’s needs.

## 2. Unique Roles

Unique roles determine the access and permissions for platform features, as described in the following documentation: [Understand Roles and Permissions](https://docs.unique.ai/it-operators/identity-and-access-management-iam/understand-roles-and-permissions).

These Roles are _also managed using Zitadel_ and should be given to users on an organisation level. To be able to give the authorizations to users, you need to have the relevant **Zitadel Roles.**

## 3. Space Access

You can manage access to specific spaces using the space management tab on the Unique App and following this documentation: [Space Management](https://docs.unique.ai/administrators/space-management).

To manage Space Access, users need to have the `admin.space.write` role, from the Unique Roles.

## 4. Scope Access (Folder in the Knowledge Base)

Scope Access determines which users or user groups can read (see) or write (add/modify) documents to which scopes (folders). Based on this access configuration, you define what knowledge the user has access to when using spaces or Unique in general.

The access to scopes (Folders) can be configured in the UI in the Knowledge base by admin users that have the `chat.admin.all` Unique role assigned in Zitadel. Refer to this documentation: [Knowledge Base for Admins](https://docs.unique.ai/administrators/knowledge-base-for-admins)

## Managing Scope Access via API

To manage scopes and groups via API, you will need these two documentations:

1. Managing Scopes: [Managing scopes & access via API](https://docs.unique.ai/developers/software-development-kit-sdk/apis-graphql-internal-apis-for-admins/user-groups-apis/managing-scopes-access-via-api)

2. Managing Groups: [Managing groups & group members via API](https://docs.unique.ai/developers/software-development-kit-sdk/apis-graphql-internal-apis-for-admins/user-groups-apis/managing-groups-group-members-via-api)

If you are starting from scratch, you need to:

1. Create a new group: [Managing groups & group members via API](https://docs.unique.ai/developers/software-development-kit-sdk/apis-graphql-internal-apis-for-admins/user-groups-apis/managing-groups-group-members-via-api)

2. Add members to the group using the API or the UI (User management in the Unique App): [User Management Interface](https://docs.unique.ai/administrators/platform-configuration/user-management-interface)

3. Create a Scope: [Managing scopes & access via API](https://docs.unique.ai/developers/software-development-kit/sdk/apis-graphql-internal-apis-for-admins/user-groups-apis/managing-scopes-access-via-api)

4. Create scope Access: [Managing scopes & access via API](https://docs.unique.ai/developers/software-development-kit/sdk/apis-graphql-internal-apis-for-admins/user-groups-apis/managing-scopes-access-via-api)