A role can be assigned with multiple scopes to a user or a user group. This allows you to provide a more granular level of access to each user. For example, an administrator may require access to an entire COMPANY or to several companies at once.
How a role's access is scoped depends on two things: how many audiences you define, and how many predicates you place inside each audience.
In updating roles of a user group API, the scope is made up of an audiences array, and each audience contains a predicates array:
"scope": {
"audiences": [ // one or more audiences
{
"predicates": [ // one or more predicates within an audience
{
"type": "COMPANY",
"comparator": "IN",
"values": ["<company identifier>"]
}
]
}
]
}The following table explains how we can narrow or broaden the access for a user group:
| Configuration | How it is combined? | Effect |
|---|---|---|
| Multiple predicates within a single audience | AND (i.e., the user must satisfy every predicate values). | Narrows access (e.g., a single COMPANY within a BOOKING_TMC) |
Multiple audiences in the audiences array | OR (i.e., the user must satisfy any one audience) | Broadens access across independent groupings. |
The following sections walk through some use cases:
The role applies to a single boundary (e.g., access scoped to just one company).
{
"rolesToAdd": [
{
"roleId": "<role-identifier>",
"scope": {
"audiences": [
{
"predicates": [
{
"type": "COMPANY",
"comparator": "IN",
"values": ["<company identifier>"]
}
]
}
]
}
}
],
"rolesToDelete": []
}As the values field is an array you can use it to define more values of the same type. For example, an administrator needs agents to manage trips across two separate client companies. They define a single audience with one COMPANY predicate whose values array contain both companyIds. The result is that the role applies to travelers in either company.
{
"rolesToAdd": [
{
"roleId": "<role identifier>",
"scope": {
"audiences": [
{
"predicates": [
{
"type": "COMPANY",
"comparator": "IN",
"values": [
"<company identifier A>",
"<company identifier B>"
]
}
]
}
]
}
}
],
"rolesToDelete": []
}When an audience contains more than one predicate, the predicates are combined with an AND functionality (i.e., the role must satisfy all of the predicate values). Use this to narrow access to the intersection of two scope types.
For example, a booking TMC wants its agents to manage trips for one specific client company only. They include two predicates in the same audience: one with type: BOOKING_TMC and the values containing the TMC's UUID, and another with type: COMPANY with values set to the client company's UUID. The result is that the role only applies to travelers in that one client company under that TMC. These agents won't be able to access the other client companies within the specific TMC.
{
"rolesToAdd": [
{
"roleId": "<role-identifier>",
"scope": {
"audiences": [
{
"predicates": [
{
"type": "BOOKING_TMC",
"comparator": "IN",
"values": ["<booking TMC identifier>"]
},
{
"type": "COMPANY",
"comparator": "IN",
"values": ["<company identifier>"]
}
]
}
]
}
}
],
"rolesToDelete": []
}When you define more than one audience in the audiences array, the audiences are combined with an OR functionality (i.e., The user falls within the role's scope if they match any one audience). Use this to broaden access across independent groupings that each have their own conditions.
For example, a booking TMC wants its agents to support all the client companies under their TMC. They also want the same agents to manage an additional company that the booking TMC doesn't manage (for example, a company under a different TMC). In this scenario the admins define two audiences: the first grants access to the entire TMC and all of its current and future clients (i.e., a single BOOKING_TMC predicate), and the second grants access to the one additional company (a single COMPANY predicate).
{
"rolesToAdd": [
{
"roleId": "<role identifier>",
"scope": {
"audiences": [
{
"predicates": [
{
"type": "BOOKING_TMC",
"comparator": "IN",
"values": ["<booking TMC identifier>"]
}
]
},
{
"predicates": [
{
"type": "COMPANY",
"comparator": "IN",
"values": ["<company identifier>"]
}
]
}
]
}
}
],
"rolesToDelete": []
}