Omni User model roles API

openapi: 3.1.0
info:
  title: Omni AI User model roles API
  description: "The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more.  \n"
  version: 1.0.0
  contact:
    name: Omni Support
    url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
  description: Production
  variables:
    instance:
      default: blobsrus
      description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
  description: Playground
  variables:
    instance:
      default: blobsrus
      description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: User model roles
  description: Manage model and connection role assignments for users
paths:
  /v1/users/{userId}/model-roles:
    post:
      tags:
      - User model roles
      summary: Assign or update user model role
      description: '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. To manage users, see the [User APIs](/api/users).

        '
      security:
      - bearerAuth: []
      operationId: assignUserModelRole
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the user to assign or update a model role for.
        example: 9e8719d9-276a-4964-9395-a493189a247c
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - roleName
              properties:
                connectionId:
                  type: string
                  format: uuid
                  description: 'The ID of the connection that the model belongs to:


                    - **Required** if `modelId` is not provided

                    - **Optional** if `modelId` is provided, in which case it will be inferred from the model

                    '
                modelId:
                  type: string
                  format: uuid
                  description: 'The ID of the model to assign the role for:


                    - **Optional** when assigning `CONNECTION_ADMIN` or [custom roles](/administration/users/custom-roles) with `CONNECTION_ADMIN` as the base role

                    - **Required** for other role types

                    '
                roleName:
                  type: string
                  description: 'The role to assign. Available roles include:


                    - `VIEWER` - Can view the model

                    - `QUERIER` - Can view and query the model

                    - `QUERY_TOPICS` - Can query specific topics. Equivalent to **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](/administration/users/custom-roles) defined for your organization

                    '
            example:
              connectionId: bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed
              modelId: 7d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a
              roleName: QUERIER
      responses:
        '200':
          description: Model role assigned or updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    format: uuid
                    description: The ID of the user.
                  connectionId:
                    type: string
                    format: uuid
                    description: The ID of the connection.
                  modelId:
                    type: string
                    format: uuid
                    description: The ID of the model.
                  roleName:
                    type: string
                    description: The assigned role name.
              example:
                userId: 9e8719d9-276a-4964-9395-a493189a247c
                connectionId: bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed
                modelId: 7d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a
                roleName: QUERIER
        '400':
          description: 'Bad Request. Possible error messages include:


            - `Invalid JSON`

            - `Invalid model ID`

            - `Invalid connection ID`

            - `Method not allowed`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'Not Found. Possible error messages include:


            - `User not found in organization`

            - `Model does not exist`

            - `Connection does not exist`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'Unprocessable Entity. Possible error messages include:


            - `Invalid role`

            - `Model does not belong to connection`

            - `Only shared and shared_extension models can be assigned model roles`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      tags:
      - User model roles
      summary: Retrieve user model roles
      description: 'Retrieves the model role assignments for a user. This includes both direct role assignments and roles inherited from user group memberships.

        '
      security:
      - bearerAuth: []
      operationId: getUserModelRoles
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the user to retrieve model roles for.
        example: 9e8719d9-276a-4964-9395-a493189a247c
      - name: modelId
        in: query
        schema:
          type: string
          format: uuid
        description: Filter results to a specific model ID. If not provided, returns roles for all models the user has access to.
        example: 7d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a
      - name: connectionId
        in: query
        schema:
          type: string
          format: uuid
        description: Filter results to models from a specific connection. If not provided, returns roles for all connections.
        example: bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed
      responses:
        '200':
          description: User model roles retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  membershipId:
                    type: string
                    format: uuid
                    description: The ID of the user's membership in the organization.
                  results:
                    type: array
                    description: Array of all role assignments for the user, including direct assignments, roles inherited from user groups, and connection base roles.
                    items:
                      type: object
                      properties:
                        modelId:
                          type: string
                          format: uuid
                          description: The ID of the model.
                        connectionId:
                          type: string
                          format: uuid
                          description: The ID of the connection.
                        roleName:
                          type: string
                          description: The role name for this assignment.
                        baseRole:
                          type: string
                          description: The base role for this assignment.
                        priority:
                          type: integer
                          description: The priority of this role assignment. Higher values take precedence.
                        resolved:
                          type: boolean
                          description: If `true`, this is the highest priority role for the model. This is the role that will be used when determining the user's effective permissions.
                        from:
                          type: object
                          description: Information about where this role assignment comes from.
                          properties:
                            type:
                              type: string
                              description: 'The type of role assignment:


                                - `User Role` - Direct role assignment to the user

                                - `Group Role` - Role inherited from a user group

                                - `Connection Base Role` - Default role from the connection

                                '
                            miniUuid:
                              type: string
                              description: The short ID of the user group. Only present for `Group Role` type.
                            name:
                              type: string
                              description: The name of the user group. Only present for `Group Role` type.
                            depth:
                              type: integer
                              description: The depth of group nesting. Only present for `Group Role` type.
              example:
                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
        '404':
          description: User not found in organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: User not found in organization
                status: 404
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: HTTP response code for the error
          example: <response_code>
        message:
          type: string
          description: Detailed error description
          example: <error_reason>
  responses:
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded (60 requests/minute)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#token-types).


        Include in the `Authorization` header as: `Bearer YOUR_TOKEN`

        '
    orgApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint.


        Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`

        '