This page explains the key concepts of Spotnana's Role-based Access Control (RBAC) system.
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.
RBAC is managed through two sets of APIs: the Roles API (for managing roles, permissions, and role assignments) and the User Groups API (for managing user groups and their members). Understanding these concepts will help you work effectively with these APIs.
A permission represents a resource on the platform paired with one or more actions that can be performed on it. In the get role API, a permission is represented using two fields: permission (the resource) and actions (an array of allowed actions).
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 endpoint or the retrieve permissions for a specific company 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. |
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 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,
WRITEdoes not automatically includeREAD. If a user needs both read and write access, both actions must be included in theactionsarray. This ensures that users only receive the exact level of access they need.
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.
The table below explains the difference between a platform role and a company role. In the get role 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 API to create a custom company role and assign permissions and actions to it. Note Currently, Spotnana does not allow creating a company role. If a custom role is needed, please reach out to your Spotnana representative. |
When listing all the roles for a company, use the filters > roleProvidedBy field to filter platform roles and company roles in the response.
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 |
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: <the company identifier> 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, 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
audiencesandpredicatesarray to define all the scopes for a role. For example, an administrator may require access to a company (i.e.,COMPANYfield) and two of its legal entities (i.e.,LEGAL_ENTITYfield). See access with multiple scopes for more information.
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.
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. |
You can create custom user groups for any specific needs of your company. See creating a custom user group workflow for more information.
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.
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:
- 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.
- 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.
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 API to view Spotnana-provided system roles.