# 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

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 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:

div
table
thead
tr
th
Application
th
Organization path used in this guide
th
Example member roles
tbody
tr
td
strong
Holiday booking platform
td
strong
Retail travel agency
— parent org / head office
td
ul
li
Booking agent
li
After-sales specialist
li
Invoice reviewer
tr
td
strong
New York branch
— managed child organization
td
ul
li
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 application will use them for authorization.

For each role, configure:

| Field | Purpose |
|  --- | --- |
| **Role name** | Display name in the Admin Portal and Organization admin portal. |
| **Description** | Optional; provides context to administrators. |
| **Value** | Stable identifier used in tokens and application logic (e.g., `booking_agent`). |


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

Permissions and the Roles API
Additional permissions can be attached to roles when created via the **[Roles API](/openapi/user/roles.openapi)**. Roles created in the Admin Portal expose only the role value; your application is responsible for enforcing access unless extended via API.

## Configure member roles

In the **Admin Portal** > **B2B Identity** > **Roles** , you define member roles for a selected application. Before creating roles, select the relevant app from the **application selector** at the top of the page.

Each member role includes a **name**, a **value** (the identifier your application relies on), and optionally a **description**, depending on your portal version.

Mosaic exposes these **role values** after sign-in—for example in the **ID token** (e.g., via the `role_values` claim) or through APIs. Your application is responsible for enforcing authorization based on these values (see [Configure org roles & auth](/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.

**Organization member roles** (e.g., Organization admin, Organization member) are managed separately. They are assigned per user under **B2B Identity** > **Organizations** > *Select organization* > **Members**, or via the Organization admin portal (see [Set members](/guides/user/b2b/b2b_set_members)).

style
/* 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;
    }