The steps below explain how to create a new custom user group for a company, assign roles with scopes to it, and add users as members to it. This is useful when your organization needs a custom access structure (in addition to the system-defined user groups provided by Spotnana). For example, creating a dedicated agent group for a specific client, or a regional travel coordinator group, or a financial analyst group with report access only.
| Step | Name | Endpoint | Details |
|---|---|---|---|
| List user roles for company | POST /v3/companies/{companyId}/roles | Browse all available roles for the company to identify which roles you want to assign to the new user group. You can filter to view only platform-provided roles, only custom company roles, or both. URL path requires: companyId.Request body requires: filters with roleProvidedBy (values: PLATFORM, COMPANY) or specific roleIds.Response will contain: roles (an array of role objects each containing id, name, description, isPlatformRole, companyId, permissions with permission name and actions, createdAt, updatedAt, createdBy, and updatedBy).Other APIs will use: roles > id (the roleId values to be assigned in Step 4). | |
| List all permissions on the platform (optional) | GET /v3/permissions | Retrieve the full catalog of platform permissions to understand what each role grants. This is helpful when deciding which roles best fit the intended purpose of the new user group. Response will contain: an array of permissions objects each containing name (e.g., TMC_MANAGEMENT) along with a description and an optional parentName. | |
| Create user group | POST /v3/companies/{companyId}/user-groups | Create a new custom user group for the company. URL path requires: companyId.Request body requires: name (a descriptive name for the group, between 1–255 characters) and description (explaining the group's purpose, up to 1000 characters).Response will contain: id (the unique identifier of the newly created user group).Other APIs will use: id (referred to as groupId in subsequent steps). | |
| Update user group roles | PATCH /v3/companies/{companyId}/user-groups/{groupId}/roles | Assign roles with scopes to the newly created user group. URL path requires: companyId and groupId (from Step 3).Request body requires: rolesToAdd. This is an array of objects, each containing the roleId from Step 1 and a scope object defining the audiences with predicates (e.g., PLATFORM) and an optional id for the target entity. Also provide rolesToDelete (pass an empty array since this is a new group with no existing role assignments).Note: See the access with multiple scope predicates guide if you're adding multiple scopes for a role. Response will contain: a 200 status code confirming the roles were assigned successfully. | |
| Update user group members | PATCH /v3/companies/{companyId}/user-groups/{groupId}/members | Add users to the newly created user group. URL path requires: companyId and groupId (from Step 3).Request body requires: userIdsToAdd (an array of user IDs to add to the group).Note: Users being added must belong to the same company as the user group. Once added, they will automatically inherit all roles and scopes assigned in Step 4. Users can belong to multiple user groups simultaneously. Adding them here does not remove them from any other group. Response will contain: a 200 status code confirming the members were added successfully. | |
| List user group roles (optional) | POST /v3/companies/{companyId}/user-groups/{groupId}/roles | Verify that the roles are correctly assigned by listing the roles assigned to the new user group. URL path requires: companyId and groupId (from Step 3).Response will contain: roles (an array of role objects each containing role details with id, name, description, isPlatformRole, permissions, and associated scope information). All roles and scopes assigned in Step 4 should appear in this list. | |
| List user group members (optional) | POST /v3/companies/{companyId}/user-groups/{groupId}/members | Verify that all intended users have been added to the group. URL path requires: companyId and groupId (from Step 3).Response will contain: members (an array of member objects each containing userId and addedAt). All users added in Step 5 should appear in this list, confirming the custom user group is fully configured with roles, scopes, and members. |