This page is the detail for 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.
Take the holiday booking platform and travel agencies story from 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:
| Application | Organization path used in this guide | Example member roles |
|---|---|---|
| Holiday booking platform | Retail travel agency — parent org / head office |
|
| New York branch — managed child organization |
|
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 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).
Additional permissions can be attached to roles when created via the Roles API. Roles created in the Admin Portal expose only the role value; your application is responsible for enforcing access unless extended via API.
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).
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).