The steps below explain how to create a custom agent user group scoped to a specific client organization. This is a common use case for when you want certain agents to only service a particular client, rather than all organizations under the TMC. For example, a TMC may want to create a "Dedicated Client Agents" group where the agents in that group can only view and manage travel for a specific client's employees, with no visibility into other organizations.
Note: In the above example, since the agents are only provided access to a specific client organization, use the list user groups for a user API to make sure they are not part of any other user groups that give them access to other client organization profiles.
| Step | Name | Endpoint | Details |
|---|---|---|---|
| List user roles for company | POST /v3/companies/{companyId}/roles | Browse all available roles to identify which ones the client-specific agent group needs. For a typical client-specific agent setup, you would look for roles such as Agent, Trip Manager, and Company Management Admin (Read Only). URL path requires: companyId.Response will contain: roles (an array of role objects each containing id, name, description, and other relevant details).Other APIs will use: roles > id (the roleId values to be assigned with client-specific scope in Step 4). | |
| Get role (optional) | GET /v3/roles/{roleId} | View the full details of each role you plan to assign to confirm its permissions are appropriate for the client-specific agents. Repeat this step for each role identified in Step 1. URL path requires: roleId (from Step 1).Response will contain: the full role object including id, name, description, isPlatformRole, permissions (an array of objects each containing a permission name and actions such as READ, WRITE, CREATE, DELETE, PURGE, or ALL), createdAt, updatedAt, createdBy, and updatedBy. | |
| Create user group | POST /v3/companies/{companyId}/user-groups | Create the new client-specific agent user group. URL path requires: companyId.Request body requires: name (a descriptive name that identifies both the client and function) and description (explaining the group's purpose).For example: * name: "Dedicated Client Agents"* description: "Agents dedicated to managing travel for a specific client's employees only"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 the selected roles to the group with scope narrowed to the specific client organization. This is the key step where the client-specific access boundary is defined. URL path requires: companyId and groupId (from Step 3).Request body requires: rolesToAdd (an array of objects, each containing a roleId from Step 1 and a scope object). To scope each role to a specific client organization, define the audiences with a predicates array containing a single predicate where type is COMPANY and values is the UUID of the target client organization.Note: All members of the user group will automatically inherit the scoped roles. Agents in this group will only see and manage resources within the defined scope, with no visibility into other organizations under the TMC. 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 the agents who will be servicing this specific client to the group. URL path requires: companyId and groupId (from Step 3).Request body requires: userIdsToAdd (an array of user IDs for the agents to add).Note: Users being added must belong to the same company. Once added, these agents will automatically inherit the scoped roles from Step 4 and will only have access to the specified client organization's travelers and bookings. Agents can belong to multiple user groups simultaneously, so adding them here does not affect their membership in other groups such as a broader TMC Agent group. Response will contain: a 200 status code confirming the members were added successfully. | |
| List user group roles | POST /v3/companies/{companyId}/user-groups/{groupId}/roles | Verify that the roles and client-specific scopes have been assigned correctly. 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). Confirm that each role's scope contains the correct COMPANY predicate with the target client organization's ID. | |
| List user group members (optional) | POST /v3/companies/{companyId}/user-groups/{groupId}/members | Verify that all intended agents 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 agents added in Step 5 should appear in this list, confirming the client-specific agent group is fully configured and operational. |