openapi: 3.0.3
info:
  title: Roles
  description: Manage user roles and permissions
  version: ''
servers:
  - url: https://api.sbx.transmitsecurity.io/cis
    description: Sandbox environment
  - url: https://api.transmitsecurity.io/cis
    description: Production environment (US)
  - url: https://api.eu.transmitsecurity.io/cis
    description: Production environment (EU)
  - url: https://api.ca.transmitsecurity.io/cis
    description: Production environment (CA)
  - url: https://api.au.transmitsecurity.io/cis
    description: Production environment (AU)
security: []
paths:
  /v1/applications/{app_id}/roles/{role_id}/assignments:
    post:
      operationId: assignRoleToEntity
      summary: Assign role
      description: Assign a role to users or groups
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application
          schema:
            type: string
        - name: role_id
          required: true
          in: path
          description: ID of the role to assign
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiAssignRoleInput'
      responses:
        '204':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - AdminAccessToken: []
  /v1/applications/{app_id}/roles/{role_id}/assignments/{entity_id}:
    delete:
      operationId: removeAssignedRoleFromEntity
      summary: Revoke role
      description: Delete user or group assignment from a role
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application
          schema:
            type: string
        - name: role_id
          required: true
          in: path
          description: ID of the role to revoke
          schema:
            type: string
        - name: entity_id
          required: true
          in: path
          description: ID of the user or group to revoke role from
          schema:
            type: string
      responses:
        '204':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - AdminAccessToken: []
  /v1/applications/{app_id}/roles:
    post:
      operationId: createRoleInApp
      summary: Create role
      description: >-
        Create a new role for this application. <br><br>**Required
        permissions**: `organizations:create`, `roles:create`.
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application to retrieve its roles
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCreateRoleInput'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                title: ApiCreatedResponse-createRoleInApp
                type: object
                required:
                  - result
                description: The Role has been successfully created.
                properties:
                  result:
                    $ref: '#/components/schemas/GetRoleIdResponse'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentifierIsTakenHttpError'
      security:
        - AdminAccessToken: []
    get:
      operationId: getAppRoles
      summary: Get roles
      description: >-
        Retrieve a list of all roles created for this application.
        <br><br>**Required permissions**: `organizations:read`, `roles:read`,
        `organizations:list`, `roles:list`.
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application to retrieve it's roles
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getAppRoles
                type: object
                required:
                  - result
                description: ''
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiRole'
      security:
        - AdminAccessToken: []
  /v1/applications/{app_id}/roles/{role_id}:
    get:
      operationId: getAppRoleById
      summary: Get role by ID
      description: >-
        Retrieve a role by ID. <br><br>**Required permissions**:
        `organizations:read`, `roles:read`.
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application to retrieve its roles
          schema:
            type: string
        - name: role_id
          required: true
          in: path
          description: ID of the role to retrieve
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getAppRoleById
                type: object
                required:
                  - result
                description: The role has been successfully fetched.
                properties:
                  result:
                    $ref: '#/components/schemas/ApiRole'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - AdminAccessToken: []
    put:
      operationId: updateRoleInApp
      summary: Update role
      description: >-
        Update an existing role for this application. <br><br>**Required
        permissions**: `organizations:edit`, `roles:edit`.
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application to retrieve it's roles
          schema:
            type: string
        - name: role_id
          required: true
          in: path
          description: ID of the role to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUpdateRoleInput'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRoleIdResponse'
      security:
        - AdminAccessToken: []
    delete:
      operationId: deleteRoleFromApp
      summary: Delete role
      description: >-
        Delete role from this application. <br><br>**Required permissions**:
        `organizations:delete`, `roles:delete`.
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application to delete the role from
          schema:
            type: string
        - name: role_id
          required: true
          in: path
          description: ID of the role to delete
          schema:
            type: string
      responses:
        '202':
          description: ''
      security:
        - AdminAccessToken: []
components:
  schemas:
    ApiAssignRoleInput:
      type: object
      properties:
        entity_ids:
          type: array
          items:
            type: string
          description: >-
            List of entities to assign the role. All entites must be of the same
            type.
        entity_type:
          type: string
          enum:
            - User
            - Group
            - Application
          title: Entity type
          description: >-
            Type of entities to assign the role. All entities in entity_ids must
            be of this type.
      required:
        - entity_ids
        - entity_type
    NotFoundHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
          example: 404
      required:
        - message
        - error_code
    ApiRole:
      type: object
      properties:
        role_id:
          type: string
          description: Role ID
        role_name:
          type: string
          description: Role name
        permissions:
          description: Role permissions
          type: array
          items:
            type: string
        app_id:
          type: string
          description: Role's app id
        description:
          type: string
          description: Role's description
        display_name:
          type: string
          description: Role's display name
      required:
        - role_id
        - role_name
    ApiCreateRoleInput:
      type: object
      properties:
        role_name:
          type: string
          description: Role name
        permissions:
          description: Role permissions
          type: array
          items:
            type: string
        description:
          type: string
          description: Role description
        display_name:
          type: string
          description: Role display name
      required:
        - role_name
    IdentifierIsTakenHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
      required:
        - message
        - error_code
    GetRoleIdResponse:
      type: object
      properties:
        result:
          type: object
      required:
        - result
    ApiUpdateRoleInput:
      type: object
      properties:
        role_name:
          type: string
          description: Role name
        permissions:
          description: Role permissions
          type: array
          items:
            type: string
        description:
          type: string
          description: Role description
        display_name:
          type: string
          description: Role display name
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    UserAccessToken:
      type: http
      description: >-
        A token returned upon end-user authentication, which provides access to
        resources and data for the user and app for which it was generated
      scheme: bearer
      bearerFormat: JWT
    AdminAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token generated by a management application using the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken). It provides
        access to all resources for the tenant and its apps
    ClientAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token generated by an end-user application using the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken). It provides
        access to resources and data on the tenant level or associated with the
        specific application (but not other apps in the tenant)
    OrgAdminAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token returned upon B2B authentication for a user that has the
        organizationAdmin or organizationCreator role.
