# Access with multiple scopes

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.

## Scope structure in the API

In [updating roles of a user group](/openapi/rbacapi/roles/updateusergrouprolesv3) API, the `scope` is made up of an `audiences` array, and each audience contains a `predicates` array:


```json
"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:

## Single audience with a single predicate

The role applies to a single boundary (e.g., access scoped to just one company).


```json PATCH /v3/companies/{companyId}/user-groups/{groupId}/roles
{
  "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 `companyId`s.
The result is that the role applies to travelers in either company.


```json PATCH /v3/companies/{companyId}/user-groups/{groupId}/roles
{
  "rolesToAdd": [
    {
      "roleId": "<role identifier>",
      "scope": {
        "audiences": [
          {
            "predicates": [
              {
                "type": "COMPANY",
                "comparator": "IN",
                "values": [
                  "<company identifier A>",
                  "<company identifier B>"
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "rolesToDelete": []
}
```

## Single audience with multiple predicates

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.


```json PATCH /v3/companies/{companyId}/user-groups/{groupId}/roles
{
  "rolesToAdd": [
    {
      "roleId": "<role-identifier>",
      "scope": {
        "audiences": [
          {
            "predicates": [
              {
                "type": "BOOKING_TMC",
                "comparator": "IN",
                "values": ["<booking TMC identifier>"]
              },
              {
                "type": "COMPANY",
                "comparator": "IN",
                "values": ["<company identifier>"]
              }
            ]
          }
        ]
      }
    }
  ],
  "rolesToDelete": []
}
```

## Multiple audiences

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).


```json PATCH /v3/companies/{companyId}/user-groups/{groupId}/roles
{
  "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": []
}
```