# RBAC concepts This page explains the key concepts of Spotnana's Role-based Access Control (RBAC) system. ## What is RBAC? Role-based Access Control (RBAC) is the model Spotnana uses to manage platform access. It provides a flexible structure that allows administrators to configure exactly what actions a user can perform and which resources they can access on the Spotnana platform. Platform permissions are grouped into roles, and roles are combined with scopes to define where those permissions apply. These role and scope pairs are then assigned to user groups or directly to user profiles. Users inherit permissions by being members of one or more user groups. For example, if you want a group of agents to only manage trips for a specific company, you would create a user group, assign the `TRIP_MANAGEMENT` role scoped to just that company, and add the agents as members of the group you created. All members of that group will automatically gain trip management permissions limited to that company. ## APIs used RBAC is managed through two sets of APIs: the [Roles API](/openapi/rbacapi/roles/createrolev3) (for managing roles, permissions, and role assignments) and the [User Groups API](/openapi/rbacapi/user-groups/createusergroup) (for managing user groups and their members). Understanding these concepts will help you work effectively with these APIs. ## Permissions and actions A permission represents a resource on the platform paired with one or more actions that can be performed on it. In the [get role](/openapi/rbacapi/roles/getrolev3) API, a permission is represented using two fields: `permission` (the resource) and `actions` (an array of allowed actions). ### Available permissions The table below lists all the available permissions and actions offered by the Spotnana APIs. You can retrieve the full list using the [list all permissions on the platform](/openapi/rbacapi/roles/listpermissions) endpoint or the [retrieve permissions for a specific company](/openapi/rbacapi/roles/listcompanypermissions) endpoint. | Permission name | What it allows | | --- | --- | | `TMC_MANAGEMENT` | Manage TMC-level settings such as TMC program configurations, agent management, and policies that apply across all client companies under the TMC. | | `COMPANY_MANAGEMENT` | Manage company-level settings such as travel policies, cost centers, legal entities, departments, offices, and other company-specific configurations. | | `USER_MANAGEMENT` | Manage user accounts including creating, updating, and deactivating user profiles within a company. This permission can also be used to update the business information (e.g., legal entity) of a user profile. | | `USER_PROFILE` | View and edit user profile details such as personal information, travel preferences, identity documents, and loyalty memberships. | | `EVENT_MANAGEMENT` | Manage group travel events including creating events, inviting travelers, and overseeing event-related bookings. | | `REPORT_MANAGEMENT` | Access reports and analytics dashboards such as travel spend, booking activity, and policy compliance reporting. | | `ACCESS_MANAGEMENT` | Manage RBAC configurations including user groups, role assignments, scope definitions, and group memberships. | | `TRIP_MANAGEMENT` | Manage trips and bookings including creating, viewing, modifying, and canceling air, hotel, car, rail, and other travel bookings. | | `AGENT` | Access agent-specific features such as the agent dashboard and tasks. | | `DEVELOPER_PLATFORM_MANAGEMENT` | Manage the developer platform. | ### Available actions Each permission can be paired with one or more of the following actions: | Action | Description | | --- | --- | | `ALL` | Grants full access to perform any action on the resource. | | `CREATE` | Allows creating new instances of the resource. | | `READ` | Allows viewing or retrieving information about the resource. | | `WRITE` | Allows modifying or updating existing instances of the resource. | | `DELETE` | Allows removing instances of the resource. | | `PURGE` | Allows permanently removing instances of the resource including any associated data. | For example, in the [get role](/openapi/rbacapi/roles/getrolev3) API, a permission that allows the viewing and editing of users would contain `permission: USER_MANAGEMENT` with `actions: [READ, WRITE]`. This grants the ability to read and modify user records, but not to create or delete them. > **Note:** Actions do not have an implied hierarchy. For example, `WRITE` does not automatically include `READ`. If a user needs both read and write access, both actions must be included in the `actions` array. This ensures that users only receive the exact level of access they need. ## Roles A role is a named collection of permissions that represents a job function. For example, a role for managing trips might contain `TRIP_MANAGEMENT` permissions with the `CREATE`, `READ`, and `WRITE` actions. A role for viewing reports might contain only the `REPORT_MANAGEMENT` permission with the `READ` action. ### Platform roles vs company roles The table below explains the difference between a platform role and a company role. In the [get role](/openapi/rbacapi/roles/getrolev3) API, the `isPlatformRole` field is used to determine the type of the role. | Type | `isPlatformRole` value equals | Description | | --- | --- | --- | | Platform role | `true` | Preconfigured and built into the Spotnana platform. These roles cannot be modified or deleted. They represent a standard set of job functions (e.g., a trip administrator role to search and book travel for other users) which can be used once the API integration. | | Company role | `false` | Custom roles created by a company to address specific needs. The `companyId` field in the response identifies which company owns the role.Use the [create role](/openapi/rbacapi/roles/createrolev3) API to create a custom company role and assign permissions and actions to it.Currently, Spotnana does not allow creating a company role. If a custom role is needed, please reach out to your Spotnana representative. | Tip When [listing all the roles for a company](/openapi/rbacapi/roles/listrolesv3), use the `filters` > `roleProvidedBy` field to filter platform roles and company roles in the response. ### Available roles The following are the available roles you can assign to a user profile: | Role name | Description | Supported permissions | Allowed actions | | --- | --- | --- | --- | | **TMC Settings Administrator** | Allows users to manage TMC settings. | `TMC_MANAGEMENT` | `ALL` | | **TMC Settings Administrator** (Read only access) | Allows users to view TMC settings. | `TMC_MANAGEMENT` | `READ` | | **Agent** | Allows users to manage agent queue tasks and traveler support requests. | `AGENT` | `ALL` | | **Company Settings Administrator** | Allows users to manage organization settings. | `COMPANY_MANAGEMENT` | `ALL` | | **Company Settings Administrator** (Read only access) | Allows users to view organization settings. | `COMPANY_MANAGEMENT` | `READ` | | **Access Management Administrator** | Allows users to manage roles and user groups. | `ACCESS_MANAGEMENT` | `ALL` | | **Reporting Administrator** | Allows users to manage reports. | `REPORT_MANAGEMENT` | `ALL` | | **Event Management Administrator** | Allows users to manage events. | `EVENT_MANAGEMENT` | `ALL` | | **Trip Administrator** | Allows users to manage trips and bookings. | `TRIP_MANAGEMENT` | `ALL` | | **User Management Administrator** | Allows users to manage traveler profiles. | `USER_MANAGEMENT` | `ALL` | | **User Profile Administrator** | Allows users to manage the information in user profiles. | `USER_PROFILE` | `ALL` | | **Developer Portal Administrator** | Allows users to manage webhook subscriptions and API users via the developer portal. | `DEVELOPER_PLATFORM_MANAGEMENT` | `ALL` | | **Developer Portal Administrator** (Read only access) | Allows users read-only access to the developer portal. | `DEVELOPER_PLATFORM_MANAGEMENT` | `READ` | ## Scopes A scope defines where a role's permissions apply. When a role is assigned to a user or a user group, it must be paired with a scope that specifies the boundary of access. The following scopes are available: | Scope type (i.e., `predicates` > `type`) | Description | | --- | --- | | `BOOKING_TMC` | Applies to a specific TMC that is responsible for managing travel for their client companies. For example, a booking TMC may be responsible for providing agent services to their client companies. | | `CONTRACTING_TMC` | Applies to a specific TMC that has contractual agreements with their client companies. For example, a contracting TMC may be responsible for managing global policies set across different client companies they manage. | | `COMPANY` | Applies to a specific company. | | `PROFILE` | Applies to specific user profiles on the platform. | | `TRIP_TEMPLATE` | Applies to specific trip and event templates. | | `STEALTH_TYPE` | An additional scope that can be used along with other scopes (e.g., `COMPANY`) that restricts a user's access within the platform. For example, a company wants to create a confidential travel group containing travelers whose trips and bookings shouldn't be accessible by any other travelers in the company. Also, the company wants to assign 2 agents to that group so they can assist with their bookings. To achieve this, the company creates a user group and assigns the scope of `COMPANY: ` and the scope `STEALTH_TYPE_1`. Then they add the travelers and the two agents into the user group. Now, any bookings these travelers make within Spotnana is hidden for other users. | When [updating a user group role](/openapi/rbacapi/roles/updateusergrouprolesv3), use the `rolesToAdd` > `scope` > `audiences` > `predicates` > `values` to define the specific identifiers and `predicates` > `type` to choose the scope type. For example, when assigning a `COMPANY` level scope to a user group, the `values` field must contain the company ID. > **Note:** Use the `audiences` and `predicates` array to define all the scopes for a role. For example, an administrator may require access to a company (i.e., `COMPANY` field) and two of its legal entities (i.e., `LEGAL_ENTITY` field). See [access with multiple scopes](/guides/rbac_guides/rbac_scope_predicates_guide) for more information. ## User groups A user group is a named collection of users who share common roles and scopes. Instead of managing permissions for each user individually, create a user group, assign one or more role and scope pairs to it, and add users as members. All members automatically inherit the permissions defined by the group's role assignments. ### System-defined user groups Spotnana provides the following predefined user groups: | User group | Available to | | --- | --- | | **TMC Administrators** | Administrators at TMCs who are responsible for managing the entire TMC program. | | **TMC Agents** | Agents at a TMC who are responsible for managing bookings across the entire TMC (e.g., more than one client or organization). | | **Company Administrators** | Company administrators who have full access to their company's profile. | | **Company Travel Arrangers** | Travel arrangers in a company who can book trips and events for other travelers. | Note You can create custom user groups for any specific needs of your company. See [creating a custom user group](/spotnana/rbac_create_custom_group_workflow) workflow for more information. ## Illustration of user group, roles, and scope The following illustrates how users, user groups, roles, and scopes relate to one another. Users are added as members of a user group; the group is assigned one or more role and scope pairs; and each member inherits the permissions defined by those roles, applied only within the assigned scope. ```mermaid flowchart TD Roles["
Roles
What can users do?

• Trip Administrator
• Agent
• Company Settings Admin
"] Scopes["
Scopes
Where do permissions apply?

• Platform
• TMC
• Organization, Legal Entity
"] Groups["
User Groups
Who are the users?

• Company Admins
• TMC Agents
• Custom Groups
"] Assignment["Assignment

User Group = Users + Roles + Scopes"] Result["Users in the group inherit all assigned roles
within the defined scopes."] Roles --> Assignment Scopes --> Assignment Groups --> Assignment Assignment --> Result style Roles fill:#4A86C8,stroke:#3A6BA0,color:#FFFFFF style Scopes fill:#3C9B7A,stroke:#2E7A60,color:#FFFFFF style Groups fill:#8260AD,stroke:#664B8A,color:#FFFFFF style Assignment fill:#EEEEEE,stroke:#999999,color:#000000 style Result fill:#F5F5F5,stroke:#CCCCCC,color:#000000 ``` ## Sample use case **Scenario:** Setting up a dedicated travel team for a client company For example, let's say a TMC needs to set up a group of agents who can manage trips and view reports for the travelers of a specific client company. The team consists of three agents (User A, User B, and User C) who should be able to create, view, and modify trip bookings as well as access reporting dashboards, but only for that one client company. They should have no visibility into any other company's data. To achieve this, the TMC administrator creates a custom user group called **Travel team** and assigns two roles to it: 1. A **Trip Administrator** role, scoped to the specific client company. This gives all members the ability to manage trips and bookings for that company's travelers. 2. A **Reporting Administrator** role, also scoped to the same company. This gives all members the ability to access and run reports for that company's travel activity. ```mermaid flowchart TD Group["User group: Travel team
User A, User B, User C"] A1["Assignment 1"] A2["Assignment 2"] Role1["Role: Trip Administrator
roleId: abc-123"] Role2["Role: Reporting Administrator
roleId: def-456"] Scope1["Scope: COMPANY
id: company-xyz"] Scope2["Scope: COMPANY
id: company-xyz"] Result["Result: All members can manage trips
and view reports for company-xyz only"] Group --> A1 Group --> A2 A1 --> Role1 A2 --> Role2 Role1 --> Scope1 Role2 --> Scope2 Scope1 --> Result Scope2 --> Result style Group fill:#E8E8E8,stroke:#666666,color:#000000 style A1 fill:#FCE8D8,stroke:#E2622E,color:#000000 style A2 fill:#FCE8D8,stroke:#E2622E,color:#000000 style Role1 fill:#FDF3DC,stroke:#E0A92E,color:#000000 style Role2 fill:#FDF3DC,stroke:#E0A92E,color:#000000 style Scope1 fill:#E3EFE0,stroke:#5AA464,color:#000000 style Scope2 fill:#E3EFE0,stroke:#5AA464,color:#000000 style Result fill:#F2E8F7,stroke:#9B59B6,color:#000000 ``` > **Note:** Both the **Trip administrator** and **Reporting administrator** roles are pre-configured and provided by Spotnana. You can always modify the scopes within these roles based on your business requirements. Use the [list user roles for a company](/openapi/rbacapi/roles/listrolesv3) API to view Spotnana-provided system roles.