User group model role APIs

The user group model role APIs allow you to manage model and connection role assignments for user groups in your Omni instance. These roles control what actions members of a user group can perform on specific models and connections.

To manage user groups themselves, see the User group APIs.

Assign or update user group model role

Assigns or updates a model role for a user group. If the user group already has a role for the specified model, this endpoint will update it to the new role. All members of the user group will inherit this role.

Model roles control what actions user group members can perform on models and connections. Available roles include:

VIEWER - Can view the model
QUERIER - Can view and query the model
QUERY_TOPICS - Can query specific topics (restricted querier)
MODELER - Can edit and model the data
CONNECTION_ADMIN - Full administrative access to the connection
NO_ACCESS - No access to the model
Custom roles defined for your organization

POST /api/v1/user-groups/:id/model-roles
curl -L -X POST 'https://blobsrus.omniapp.co/api/v1/user-groups/mEhXj6ZI/model-roles' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
    "connectionId": "bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed",
    "modelId": "7d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
    "roleName": "QUERIER"
}'

Parameters

Parameter	Type	Required	Default	Description
id	URL parameter	Yes ✓	n/a	The ID of the user group to assign or update a model role for.
connectionId	string	No X	n/a	The ID of the connection that the model belongs to. Required if `modelId` is not provided. Optional if `modelId` is provided (will be inferred from the model).
modelId	string	No X	n/a	The ID of the model to assign the role for. Optional when assigning `CONNECTION_ADMIN` or custom roles with `CONNECTION_ADMIN` as the base role. Required for other role types.
roleName	string	Yes ✓	n/a	The role to assign. Available roles include: `VIEWER`, `QUERIER`, `QUERY_TOPICS`, `MODELER`, `CONNECTION_ADMIN`, `NO_ACCESS`, or any custom role defined for your organization.

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

200 OK
{
    "userGroupId": "mEhXj6ZI",
    "connectionId": "bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed",
    "modelId": "7d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
    "roleName": "QUERIER"
}

400 Bad Request

Results from invalid request parameters. Response bodies will be an object similar to the following:

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Invalid JSON body	`Invalid JSON`
Invalid model ID	`Invalid model ID`
Invalid connection ID	`Invalid connection ID`
Method not allowed	`Method not allowed`

404 Not Found

Results from user group or resources not found in the organization. Response bodies will be an object similar to the following:

{
  "detail": "<errorReason>",
  "status": 404
}

Issue	Error detail
User group not found	`User group not found in organization`
Model not found	`Model does not exist`
Connection not found	`Connection does not exist`

422 Unprocessable Entity

Results from invalid role or model/connection mismatch. Response bodies will be an object similar to the following:

{
  "detail": "<errorReason>",
  "status": 422
}

Issue	Error detail
Invalid role	`Invalid role`
Model/connection mismatch	`Model does not belong to connection`
Invalid model type	`Only shared and shared_extension models can be assigned model roles`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Retrieve user group model roles

Retrieves the model role assignments for a user group.

GET /api/v1/user-groups/:id/model-roles?modelId=:modelId&connectionId=:connectionId
curl -L 'https://blobsrus.omniapp.co/api/v1/user-groups/mEhXj6ZI/model-roles?modelId=7d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a&connectionId=bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Parameters

Note: All parameters must be provided as query parameters.

Parameter	Type	Required	Default	Description
id	URL parameter	Yes ✓	n/a	The ID of the user group to retrieve model roles for.
modelId	Query parameter	No X	n/a	Filter results to a specific model ID. If not provided, returns roles for all models the user group has access to.
connectionId	Query parameter	No X	n/a	Filter results to models from a specific connection. If not provided, returns roles for all connections.

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

200 OK
{
    "userGroupId": "mEhXj6ZI",
    "results": [
        {
            "baseRole": "QUERIER",
            "roleName": "QUERIER",
            "connectionId": "bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed",
            "modelId": "7d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a"
        }
    ]
}

Field	Type	Description
userGroupId	string	The ID of the user group
results	array	Array of role assignments for the user group
results[].modelId	string	The ID of the model
results[].connectionId	string	The ID of the connection
results[].roleName	string	The role assigned to the user group for this model
results[].baseRole	string	The base role assigned to the user group

404 Not Found

Results from user group not found in the organization. Response bodies will be an object similar to the following:

{
  "detail": "User group not found in organization",
  "status": 404
}

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Assign or update user group model role​

Parameters​

Response​

Retrieve user group model roles​

Parameters​

Response​

Assign or update user group model role

Parameters

Response

Retrieve user group model roles

Parameters

Response