User model role APIs

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

To manage users themselves, see the User APIs.

Assign or update user model role

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

Model roles control what actions a user 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/users/:id/model-roles
curl -L -X POST 'https://blobsrus.omniapp.co/api/v1/users/9e8719d9-276a-4964-9395-a493189a247c/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 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
{
    "userId": "9e8719d9-276a-4964-9395-a493189a247c",
    "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 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 not found	`User 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 model roles

Retrieves the model role assignments for a user. This includes both direct role assignments and roles inherited from user group memberships.

GET /api/v1/users/:id/model-roles?modelId=:modelId&connectionId=:connectionId
curl -L 'https://blobsrus.omniapp.co/api/v1/users/9e8719d9-276a-4964-9395-a493189a247c/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 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 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
{
    "membershipId": "9633bd79-7bdf-4773-8952-8fdd4098e51c",
    "results": [
        {
            "baseRole": "MODELER",
            "from": {
                "type": "User Role"
            },
            "priority": 350,
            "resolved": true,
            "roleName": "MODELER",
            "connectionId": "8a464dc9-1f0e-4a9e-86fa-e1e6d970157c",
            "modelId": "5fb90312-67b1-4cca-823a-9a341d549320"
        },
        {
            "baseRole": "QUERIER",
            "from": {
                "depth": 0,
                "miniUuid": "PgjffoEu",
                "name": "Super Group",
                "type": "Group Role"
            },
            "priority": 250,
            "resolved": false,
            "roleName": "QUERIER",
            "connectionId": "8a464dc9-1f0e-4a9e-86fa-e1e6d970157c",
            "modelId": "5fb90312-67b1-4cca-823a-9a341d549320"
        },
        {
            "baseRole": "VIEWER",
            "from": {
                "type": "Connection Base Role"
            },
            "priority": 50,
            "resolved": false,
            "roleName": "VIEWER",
            "connectionId": "8a464dc9-1f0e-4a9e-86fa-e1e6d970157c",
            "modelId": "5fb90312-67b1-4cca-823a-9a341d549320"
        }
    ]
}

Field	Type	Description
membershipId	string	The ID of the user's membership in the organization
results	array	Array of all role assignments for the user, including direct assignments, roles inherited from user groups, and connection base roles
results[].modelId	string	The ID of the model
results[].connectionId	string	The ID of the connection
results[].roleName	string	The role name for this assignment
results[].baseRole	string	The base role for this assignment
results[].priority	number	The priority of this role assignment. Higher values take precedence.
results[].resolved	boolean	True if this is the highest priority role for this model. This is the role that will be used when determining the user's effective permissions.
results[].from	object	Information about where this role assignment comes from
results[].from.type	string	The type of role assignment. Can be "User Role", "Group Role", or "Connection Base Role".
results[].from.miniUuid	string	The short ID of the user group (only present for "Group Role" type)
results[].from.name	string	The name of the user group (only present for "Group Role" type)
results[].from.depth	number	The depth of group nesting (only present for "Group Role" type)

404 Not Found

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

{
  "detail": "User 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 model role​

Parameters​

Response​

Retrieve user model roles​

Parameters​

Response​

Assign or update user model role

Parameters

Response

Retrieve user model roles

Parameters

Response