{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Guides","product":"Identity Management","type":"markdown"},"seo":{"title":"Define app roles","description":"Everything about Mosaic Journeys, SDKs, and APIs","siteUrl":"https://developer.transmitsecurity.com/","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"define-app-roles","__idx":0},"children":["Define app roles"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["detail"]}," for ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/b2b/b2b_setup-overview#step-3-define-the-app-roles"},"children":["Setup overview — Step 3: Define the app roles"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define the application-level ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"understand-roles","__idx":1},"children":["Understand roles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Take the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/b2b/b2b_main-concepts"},"children":["holiday booking platform and travel agencies"]}]}," story from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/b2b/b2b_main-concepts"},"children":["Main concepts"]},". In Mosaic, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["holiday booking platform"]}," is one ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["B2B application"]},". In this guide set, the main example organization is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retail travel agency"]},", which may also manage a child organization, such as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New York branch"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this step, you define ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["role groups"]},", assign those groups to specific ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["organizations"]},", and finally choose which of the allowed roles each ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["member"]}," actually gets."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the example used across the next steps, the application supports these roles:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"b2b-wip-table-wrap"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"b2b-wip-bordered-table"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{},"children":["Application"]},{"$$mdtype":"Tag","name":"th","attributes":{},"children":["Organization path used in this guide"]},{"$$mdtype":"Tag","name":"th","attributes":{},"children":["Example member roles"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"rowSpan":"2"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Holiday booking platform"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retail travel agency"]}," — parent org / head office"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Booking agent"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After-sales specialist"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invoice reviewer"]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New York branch"]}," — managed child organization"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Booking agent"]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These roles are defined once for the whole application. Later, you decide which organizations can use which subset by placing them into ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["role groups"]},". For example, the parent organization may later receive a broader bundle, while New York branch receives a narrower one."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Later, you bundle roles into ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["role groups"]},", assign only selected groups to each organization, and with parent-child relationships expose different bundles to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["head office"]}," versus ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["branches"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"plan-member-roles","__idx":2},"children":["Plan member roles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Plan role definitions before onboarding organizations, including how your application will use them for authorization."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For each role, configure:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Role name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Display name in the Admin Portal and Organization admin portal."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional; provides context to administrators."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Value"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stable identifier used in tokens and application logic (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["booking_agent"]},")."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Role and role group values should align with your application’s permission model and the claims you consume from tokens (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/validate_tokens"},"children":["Validate tokens"]},")."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Permissions and the Roles API"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additional permissions can be attached to roles when created via the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/user/roles.openapi"},"children":["Roles API"]}]},". Roles created in the Admin Portal expose only the role value; your application is responsible for enforcing access unless extended via API."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configure-member-roles","__idx":3},"children":["Configure member roles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Admin Portal"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["B2B Identity"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Roles"]}," , you define member roles for a selected application. Before creating roles, select the relevant app from the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["application selector"]}," at the top of the page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each member role includes a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["name"]},", a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["value"]}," (the identifier your application relies on), and optionally a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["description"]},", depending on your portal version."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mosaic exposes these ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["role values"]}," after sign-in—for example in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ID token"]}," (e.g., via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role_values"]}," claim) or through APIs. Your application is responsible for enforcing authorization based on these values (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/b2b/b2b_configure_org_roles_auth"},"children":["Configure org roles & auth"]},")."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"How roles are assigned"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Roles are not assigned directly from the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Roles"]}," tab. A role must first be included in a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Organization member roles"]}," (e.g., Organization admin, Organization member) are managed separately. They are assigned per user under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["B2B Identity"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Organizations"]}," > ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Select organization"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Members"]},", or via the Organization admin portal (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/b2b/b2b_set_members"},"children":["Set members"]},")."]},{"$$mdtype":"Tag","name":"style","attributes":{},"children":["\n    /* Blockquote intro block */\n    [data-component-name=\"Markdown/Markdown\"] blockquote {\n        border-left: 4px solid #BBC5FF !important;\n        border-radius: 2px;\n        background-color: #F1F2FF !important;\n        padding: 20px 10px 15px 10px;\n        margin: 10px 1px;\n    }\n\n    /* Define app roles page — bordered example table only.\n       Theme globals set th/td border-left/right: 0 !important; this block must stay specific + !important on borders. */\n    .b2b-wip-table-wrap {\n        margin: 10px 0;\n        border-radius: 5px;\n        overflow: hidden;\n        border: 1px solid #ededf2;\n    }\n\n    table.b2b-wip-bordered-table {\n        border-collapse: collapse;\n        width: 100%;\n        margin: 0;\n    }\n\n    table.b2b-wip-bordered-table th,\n    table.b2b-wip-bordered-table td {\n        border: 1px solid #ededf2 !important;\n        padding: 10px;\n        text-align: left;\n        vertical-align: top;\n    }\n\n    table.b2b-wip-bordered-table thead th {\n        background-color: #f5f5f5 !important;\n        color: #000000 !important;\n        font-weight: 600 !important;\n    }\n\n    table.b2b-wip-bordered-table ul {\n        margin: 0;\n        padding-left: 1.25em;\n    }\n"]}]},"headings":[{"value":"Define app roles","id":"define-app-roles","depth":1},{"value":"Understand roles","id":"understand-roles","depth":2},{"value":"Plan member roles","id":"plan-member-roles","depth":2},{"value":"Configure member roles","id":"configure-member-roles","depth":2}],"frontmatter":{"markdown":{"toc":{"depth":2}},"navigation":{"previousButton":{"text":"Previous:","hide":false,"label":"Implement B2B authentication","link":"/guides/user/b2b/b2b_implement_authentication"},"nextButton":{"text":"Next:","hide":false,"label":"Create app role groups","link":"/guides/user/b2b/b2b_create_role_groups"}},"seo":{"title":"Define app roles"}},"lastModified":"2026-05-14T12:07:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/user/b2b/b2b_define_app_roles","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}