openapi: 3.2.0
info:
  title: Roles API
  version: ''
servers:
- url: https://{tenant}.{region}.qlikcloud.com
  variables:
    region:
      default: us
      description: The region the tenant is hosted in
    tenant:
      default: your-tenant
      description: Name of the tenant that will be called
tags:
- name: Roles
paths:
  /api/v1/roles:
    get:
      tags:
      - Roles
      summary: List roles
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRolesResult'
          description: An array of roles, and pagination links.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Invalid request parameters for querying roles.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Unauthorized, JWT is invalid or not provided.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          headers:
            retry-after:
              schema:
                type: integer
                default: 1
              description: The amount of seconds to wait before retrying the request.
          description: Request has been rate limited.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Internal server error.
      parameters:
      - in: query
        name: filter
        schema:
          type: string
        description: The advanced filtering to use for the query. Refer to [RFC 7644](https://datatracker.ietf.org/doc/rfc7644/) for the syntax. All conditional statements within this query parameter are case insensitive.
      - in: query
        name: limit
        schema:
          type: number
          default: 20
          maximum: 100
          minimum: 1
        description: The number of roles to retrieve.
      - in: query
        name: next
        schema:
          type: string
          format: uid
          example: 507f191e810c19729de860ea
        description: The next page cursor.
      - in: query
        name: prev
        schema:
          type: string
          format: uid
          example: 507f191e810c19729de86gea
        description: The previous page cursor.
      - in: query
        name: sort
        schema:
          type: string
        description: Optional resource field name to sort on, eg. name. Can be prefixed with +/- to determine order, defaults to (+) ascending.
      - in: query
        name: totalResults
        schema:
          type: boolean
        description: Determines wether to return a count of the total records matched in the query. Defaults to false.
      description: Returns a list of roles using cursor-based pagination.
      operationId: getRoles
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '1'
        limit: 1000
    post:
      tags:
      - Roles
      summary: Create role
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Invalid request was made.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Unauthorized to create role.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Forbidden from creating role.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          headers:
            retry-after:
              schema:
                type: integer
                default: 1
              description: The amount of seconds to wait before retrying the request.
          description: Request has been rate limited.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Internal server error.
      description: Creates a custom role. Role names must be unique, and there is a maximum of 500 custom roles per tenant. Requestor must be assigned the `TenantAdmin` role.
      operationId: createRole
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRole'
        required: true
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
  /api/v1/roles/{id}:
    get:
      tags:
      - Roles
      summary: Get role by ID
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
          description: Request successfully completed.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Role ID not found or Invalid format.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          headers:
            retry-after:
              schema:
                type: integer
                default: 1
              description: The amount of seconds to wait before retrying the request.
          description: Request has been rate limited.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Internal Server Error.
      parameters:
      - in: path
        name: id
        schema:
          $ref: '#/components/schemas/Role/properties/id'
        required: true
        description: The unique identifier for the role.
      description: Returns the requested role.
      operationId: getRoleById
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '1'
        limit: 1000
    patch:
      tags:
      - Roles
      summary: Update role by ID
      responses:
        '204':
          content:
            application/json: {}
          description: Updated
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Invalid request was made.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Unauthorized to update role.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Forbidden from updating role.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Role ID not found or Invalid format.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          headers:
            retry-after:
              schema:
                type: integer
                default: 1
              description: The amount of seconds to wait before retrying the request.
          description: Request has been rate limited.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Internal server error.
      parameters:
      - in: path
        name: id
        schema:
          $ref: '#/components/schemas/Role/properties/id'
        required: true
        description: The unique identifier for the role.
      description: Updates the requested role. Only applicable to roles of type `custom`. Requestor must be assigned the `TenantAdmin` role.
      operationId: updateRoleById
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchRoles'
        required: true
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
    delete:
      tags:
      - Roles
      summary: Delete role by ID
      responses:
        '204':
          content:
            application/json: {}
          description: Deleted successfully.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Invalid request was made.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Unauthorized to delete role.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Forbidden from deleting role.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          headers:
            retry-after:
              schema:
                type: integer
                default: 1
              description: The amount of seconds to wait before retrying the request.
          description: Request has been rate limited.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Internal server error.
      parameters:
      - in: path
        name: id
        schema:
          $ref: '#/components/schemas/Role/properties/id'
        required: true
        description: The unique identifier for the role.
      description: Deletes the requested role. Role can only be deleted if it has been unassigned from all users and groups. Only applicable to roles of type `custom`. Requestor must be assigned the `TenantAdmin` role.
      operationId: deleteRoleById
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
components:
  schemas:
    PatchRole:
      type: object
      required:
      - op
      - path
      - value
      properties:
        op:
          enum:
          - replace
          - add
          - remove-value
          type: string
          example: replace
        path:
          enum:
          - /name
          - /description
          - /assignedScopes
          - /assignedScopes/-
          type: string
        value:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
      description: A JSON Patch document as defined in http://tools.ietf.org/html/rfc6902.
    Role:
      type: object
      required:
      - id
      - tenantId
      - name
      - type
      - description
      - createdAt
      - lastUpdatedAt
      - links
      properties:
        id:
          type: string
          format: uid
          example: 507f191e810c19729de860ea
          readOnly: true
          description: The unique identifier for the role.
          x-qlik-filterable: true
        name:
          type: string
          example: My Custom Role
          description: The name of the role.
          x-qlik-filterable: true
        type:
          enum:
          - default
          - custom
          type: string
          example: custom
          description: The type of role.
          x-qlik-filterable: true
        level:
          enum:
          - admin
          - user
          type: string
          example: user
          description: The level of access associated to the role.
          x-qlik-filterable: true
        links:
          type: object
          required:
          - self
          properties:
            self:
              type: object
              required:
              - href
              properties:
                href:
                  type: string
                  format: uri
                  example: http://mytenant.us.qlikcloud.com/api/v1/roles/507f191e810c19729de860ea
                  description: Link to the role.
          description: Contains links for the role.
        canEdit:
          type: boolean
          default: false
          readOnly: true
          description: Indicate if role can be edited by tenant (Shown as Profile in MC)
        fullUser:
          type: boolean
          readOnly: true
          description: DEPRECATED. Use userEntitlementType instead for impact of roles on user entitlements with a capacity-based subscription.
          x-qlik-deprecated: true
        tenantId:
          type: string
          format: uid
          example: q3VRZ4YMixRaLKEPhkZWM-XMIDN7cO8f
          description: The tenant unique identifier associated with the given Role.
          x-qlik-filterable: true
        canDelete:
          type: boolean
          default: false
          readOnly: true
          description: Indicate if role can be deleted
        createdAt:
          type: string
          format: date-time
          example: '2021-03-21T17:32:28Z'
          description: The timestamp for when the role was created.
          x-qlik-filterable: true
        createdBy:
          type: string
          readOnly: true
          description: Id of user that created role
        updatedBy:
          type: string
          readOnly: true
          description: Id of user that last updated this role
        description:
          type: string
          example: Grants permission to edit resource 'foo'
          description: Descriptive text for the role.
          x-qlik-filterable: true
        permissions:
          type: array
          items:
            type: string
          example:
          - edit_foo
          description: An array of permissions associated with the role.
          x-qlik-filterable: true
        lastUpdatedAt:
          type: string
          format: date-time
          example: '2021-03-22T10:01:02Z'
          description: The timestamp for when the role was last updated.
          x-qlik-filterable: true
        assignedScopes:
          type: array
          items:
            type: string
          description: Selection of scopes added to this Role
        userEntitlementType:
          type: string
          example: fullUser
          readOnly: true
          description: Indicate whether this role will trigger promotion of a user from a basic to a full user on tenants with a capacity-based subscription. Does not apply to tenants with a user-based subscription. Returns fullUser if it will trigger promotion.
    Error:
      type: object
      required:
      - code
      - title
      properties:
        code:
          type: string
          description: The error code.
        meta:
          type: object
          description: Additional properties relating to the error.
        title:
          type: string
          description: Summary of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        source:
          type: object
          properties:
            pointer:
              type: string
              description: A JSON Pointer to the property that caused the error.
            parameter:
              type: string
              description: The URI query parameter that caused the error.
          description: References to the source of the error.
      description: An error object describing the error.
    Errors:
      type: object
      example:
        errors:
        - code: IDENTITIES-10402
          title: Not Found
        traceId: 0000000000000000200ba0714061b982
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: An array of errors related to the operation.
        traceId:
          type: string
          description: A unique identifier for tracing the error.
      description: The error response object describing the error from the handling of an HTTP request.
    PatchRoles:
      type: array
      items:
        $ref: '#/components/schemas/PatchRole'
      example:
      - op: replace
        path: /name
        value: Role1
      - op: replace
        path: /assignedScopes
        value:
        - knowledgebase
      - op: add
        path: /assignedScopes/-
        value: knowledgebase
      - op: remove-value
        path: /assignedScopes
        value: knowledgebase
      - op: replace
        path: /description
        value: My custom role description
      description: An array of JSON Patch documents
    ListRolesResult:
      type: object
      required:
      - links
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Role'
          description: An array of roles.
        links:
          $ref: '#/components/schemas/Links'
        totalResults:
          type: integer
          description: Indicates the total number of matching documents. Will only be returned if the query parameter "totalResults" is true.
    Links:
      type: object
      required:
      - self
      properties:
        next:
          type: object
          required:
          - href
          properties:
            href:
              type: string
              format: uri
              example: http://mytenant.us.qlikcloud.com/api/v1/roles?next=QaFdFYW6pImZvRgFaDyB1UffNgfs4mRd
          description: Link to the next page of items
        prev:
          type: object
          required:
          - href
          properties:
            href:
              type: string
              format: uri
              example: http://mytenant.us.qlikcloud.com/api/v1/roles?prev=QaFdFYW6pImZvRgFaDyB1UffNgfs4mRd
          description: Link to the previous page of items
        self:
          type: object
          required:
          - href
          properties:
            href:
              type: string
              format: uri
              example: http://mytenant.us.qlikcloud.com/api/v1/roles
          description: Link to the current page of items
      description: Contains pagination links
    CreateRole:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Role name, needs to be unique
        description:
          type: string
          description: Role description
        assignedScopes:
          type: array
          items:
            type: string
          description: Selection of scopes to assign to role