# Create Role Mapping

Define a new role mapping with IDP role and permissions.

## Pages routes

- `/system/settings/roles` — List, search and manage all role mappings.
- `/system/settings/roles/create` — Create a new role. *(this page)*
- `/system/settings/roles/{uuid}` — View and edit an existing role.

## What you can do here

### How to create a new role mapping
1. On the **Roles** list page, click **New** in the toolbar.
2. Fill in the fields below — required: **role**, **org**, **label key**, **selected permissions**.
3. Click **Save** — the new role mapping is created.

## Fields

| Field | Required | Notes |
|-------|----------|-------|
| **IDP Role** | required | text input |
| **Organization** | required | text input — only organizations backed by a real identity-provider organization are listed |
| **Label Key** | required | text input |
| **Admin** | optional | checkbox |
| **Permissions** | required | text input |

- The **IDP Role** field is a required text input.
- The **Organization** field is a required text input — only organizations backed by a real identity-provider organization are listed.
- The **Label Key** field is a required text input.
- The **Admin** field is an optional checkbox.
- The **Permissions** field is a required text input.

## Related entities

- A **Role Mapping** is linked to **Organizations** through the **Organization** field — see [Organizations](/backend/guide/generated/organizations).
- A **Role Mapping** is linked to **Roles** through the **Permissions** field — see [Roles](/backend/guide/generated/roles).

## Actions

| Action | Status | Permission | What it does | Require Step-Up Auth |
|--------|--------|------------|--------------|----------------------|
| **Save** | ENABLED | `role_mapping.create.single` | Validates the form and creates the role mapping | no |
| **Cancel** | ENABLED | — | Discards changes and returns to the previous page | no |

- The **Save** action is available on this page — validates the form and creates the role mapping and it requires the `role_mapping.create.single` permission.
- The **Cancel** action is available on this page — discards changes and returns to the previous page.

## Doc references

- [Roles](/backend/guide/generated/roles)
- [Roles Edit](/backend/guide/generated/roles-edit)
- [Organizations](/backend/guide/generated/organizations)
- [Entities Crud](/backend/dev/entities-crud)