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 | table identifier used in tokens and application logic (e.g., booking_agent). |
| Display name | Display name in the Admin Portal and Organization admin portal. |
| Description | Optional; provides context to administrators. |
| Permissions | Optional project-specific labels associated with the role, such as create_booking or review_invoices. Mosaic can surface them in token claims or APIs as role metadata for the customer application to display or consume. They do not by themselves unlock functionality in Mosaic. |
Role and role group values should align with your application’s permission model and the claims you consume from tokens (see Validate tokens).
In the Admin Portal > Applications > your app > User roles tab, you define member roles for the selected application.
Each member role includes a Role name, Permissions, and optionally a Display name and description.
After sign-in, Mosaic can expose the resulting role metadata to your 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 & 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).