# Define app roles

> This page is the **detail** for [Setup overview — Step 3: Define the app roles](/guides/user/b2b/b2b_setup-overview#step-3-define-the-app-roles).
Define the application-level **member roles** that describe what a member is allowed to do inside your app — these are the building blocks you will group into role groups in the next step.


## Understand roles

Three things are called role
A quick recap, since [Main concepts](/guides/user/b2b/b2b_main-concepts#roles-and-role-groups) is a few pages back:

- **Member roles** — what a member can do in **your application**. They're what this page is about.
- **Organization-level roles**, such as Organization admin and Organization member — what a member can do in **the organization itself**, inside Mosaic. You don't define them here: they're assigned per member under **B2B Identity** > **Organizations** > *Select organization* > **Members** tab, or from the Organization admin portal.
- **Role groups** aren't a third kind of role. They're the bundles that decide which of your member roles each organization is allowed to use.


Assigning a member an Organization admin role gives them nothing in your application, and assigning them a member role gives them nothing in Mosaic.

Take the **[holiday booking platform and travel agencies](/guides/user/b2b/b2b_main-concepts)** story from [Main concepts](/guides/user/b2b/b2b_main-concepts). In Mosaic, the **holiday booking platform** is one **B2B application**. In this guide set, the main example organization is the **Retail travel agency**, which may also manage a child organization, such as **New York branch**.

In this step, you define **every member role** the Mosaic application might need at application level, even if only some organizations will use a given role later. These roles are part of the application's shared catalog: later you will bundle them into **role groups**, assign those groups to specific **organizations**, and finally choose which of the allowed roles each **member** actually gets.

For the example used across the next steps, the application supports these roles:

Application
Organization path used in this guide
Example member roles
Holiday booking platform
Retail travel agency
— parent org / head office
Booking agent
After-sales specialist
Invoice reviewer
New York branch
— managed child organization
Booking agent
These roles are defined once for the whole application. Later, you decide which organizations can use which subset by placing them into **role groups**. For example, the parent organization may later receive a broader bundle, while New York branch receives a narrower one.

Later, you bundle roles into **role groups**, assign only selected groups to each organization, and with parent-child relationships expose different bundles to the **head office** versus **branches**.

## Plan member roles

Plan role definitions before onboarding organizations, including how your customer-facing application will use them for authorization.

For each role, configure:

| Field | Purpose |
|  --- | --- |
| **Role name** | Required; stable identifier used in tokens and customer-facing application logic (e.g., `booking_agent`). It can't be changed after the role is created. |
| **User role ID** | Read-only identifier generated by Mosaic when the role is created. Use it to reference the role from the APIs. |
| **Display name** | Optional; name shown in the Admin Portal and Organization admin portal. |
| **Permissions** | Required; project-specific labels associated with the role, such as `create_booking` or `review_invoices`. They're returned in the ID token claims so that your customer-facing application can apply its own authorization logic to the member. Mosaic doesn't interpret them, and they don't by themselves unlock functionality in Mosaic. |
| **Description** | Optional; provides context to administrators. |


Role and role group values should align with your customer-facing application’s permission model and the claims you consume from tokens (see [Validate tokens](/guides/user/validate_tokens)).

## Configure member roles

In the **Admin Portal** > **Applications** > your app > **Access control** tab > **Roles**, you define member roles for the selected application. Select **+ Add user role** to create one.

Each member role requires a **Role name** and at least one entry under **Permissions**, and optionally takes a **Display name** and a **Description**.

Through the [Roles API](/openapi/user/roles.openapi), only the role name is required: permissions, display name, and description are optional.

After sign-in, Mosaic can expose the resulting role metadata to your customer-facing application through token claims—for example, `role_values` and requested `permissions` claims in the **ID token**—or through APIs. Your application can use this data for display or other project-specific logic, but Mosaic does not interpret these permissions or use them to unlock functionality in the customer application (see [Configure org roles](/guides/user/b2b/b2b_configure_org_roles_auth)).

How roles are assigned
Roles are not assigned directly from the **Roles** tab. A role must first be included in a **role group**, and that role group must be assigned to an organization. After that, an admin can assign to each member only the app-level roles that belong to the organization's assigned role groups.

/* Blockquote intro block */
    [data-component-name="Markdown/Markdown"] blockquote {
        border-left: 4px solid #BBC5FF !important;
        border-radius: 2px;
        background-color: #F1F2FF !important;
        padding: 20px 10px 15px 10px;
        margin: 10px 1px;
    }

    /* Define app roles page — bordered example table only.
       Theme globals set th/td border-left/right: 0 !important; this block must stay specific + !important on borders. */
    .b2b-wip-table-wrap {
        margin: 10px 0;
        border-radius: 5px;
        overflow: hidden;
        border: 1px solid #ededf2;
    }

    table.b2b-wip-bordered-table {
        border-collapse: collapse;
        width: 100%;
        margin: 0;
    }

    table.b2b-wip-bordered-table th,
    table.b2b-wip-bordered-table td {
        border: 1px solid #ededf2 !important;
        padding: 10px;
        text-align: left;
        vertical-align: top;
    }

    table.b2b-wip-bordered-table thead th {
        background-color: #f5f5f5 !important;
        color: #000000 !important;
        font-weight: 600 !important;
    }

    table.b2b-wip-bordered-table ul {
        margin: 0;
        padding-left: 1.25em;
    }