> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# connectionRoles

> Specifies the level of access users will have to all models associated with a connection.

<Note>
  This parameter is not required to create valid embed requests, but Omni recommends setting it.
</Note>

An object of connection roles available for embed users, used to specify the level of access users will have to all models associated with the connection. To specify permissions for individual models, use the [`modelRoles`](/embed/setup/url-parameters/modelRoles) parameter.

## Syntax

```markdown theme={null}
connectionRoles=<encoded_object>
```

## Properties

<ParamField path="connectionRoles" type="object">
  An object containing connection ID and role pairs, formatted as `"<connection_id>": "<connection_role>"`. `connection_role` values must the name of a standard user role **or** the name of a [custom user role](/administration/users/custom-roles) that resolves to either a **Viewer** or **Restricted Querier**.

  * `RESTRICTED_QUERIER` - Can create new content and view workbooks and dashboards
  * `VIEWER` - Can only view dashboards
  * `<CUSTOM_ROLE_NAME>` - Abilities depend on the role's included permissions

  **Example input**: `{"connection-id-1":"RESTRICTED_QUERIER", "connection-id-2":"CUSTOM_VIEWER"}`

  <Warning>
    Base access roles are not respected. Connection roles should be specified using this parameter or by setting group permissions on the connection in Omni and then assigning embed users to those [groups](/embed/setup/url-parameters/groups).
  </Warning>
</ParamField>

## Behavior

When a user creates an embed session, the `connectionRoles` value on the latest request acts as the source of truth for that user's connection access. This means:

* A role can be **downgraded** by a later request (e.g. from **Restricted Querier** to **Viewer**).
* A role can be **removed** entirely if the later request doesn't mention the connection — either explicitly in `connectionRoles` or implicitly in the connection backing the requested [`contentPath`](/embed/setup/url-parameters/contentPath).

To avoid unintentionally changing a user's access, include `connectionRoles` on every request.

## Examples

The following example demonstrates what the URL encoded version of `connectionRoles={"65b10d2a-473b-4486-92c8-0ba628c7d1cb":"RESTRICTED_QUERIER"}` would be:

```markdown wrap title="Example connectionRoles" theme={null}
connectionRoles=%7B%2265b10d2a-473b-4486-92c8-0ba628c7d1cb%22%3A%22RESTRICTED_QUERIER%22%7D
```