openapi: 3.0.3
info:
  title: Consents
  description: >-
    Manage consent requests and consents. These APIs allow third party clients
    to request consent from app users. They also allow users to grant consent
    requests, view all consents related to their account, and revoke any granted
    permissions.
  version: ''
servers:
  - url: https://api.transmitsecurity.io/cis
    description: Production environment (US, worldwide, except EU & Canada)
  - url: https://api.eu.transmitsecurity.io/cis
    description: Production environment (EU)
  - url: https://api.ca.transmitsecurity.io/cis
    description: Production environment (CA)
security: []
paths:
  /v1/consents:
    get:
      operationId: getAllConsents
      summary: Get all consents
      description: >-
        Retrieve all consents. <br><br>**Required permissions**: `apps:read`,
        `[appId]:read`, `consents:read`.
      security:
        - ClientAccessToken: []
      parameters:
        - name: client_id
          required: false
          in: query
          description: >-
            ID of the client whose consents are to be retrieved. If not
            provided, all consents will be retrieved.
          schema:
            type: string
        - name: user_id
          required: false
          in: query
          description: >-
            ID of the user whose consents are to be retrieved. If not provided,
            all consents will be retrieved.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getAllConsents
                type: object
                required:
                  - result
                description: Consent information
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiConsent'
  /v1/consents/{consentId}:
    get:
      operationId: getConsent
      summary: Get consent by ID
      description: >-
        Retrieve a consent by ID. <br><br>**Required permissions**: `apps:read`,
        `[appId]:read`, `consents:read`.
      parameters:
        - name: consentId
          required: true
          in: path
          description: ID of the consent to retrieve
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getConsent
                type: object
                required:
                  - result
                description: Consent information
                properties:
                  result:
                    $ref: '#/components/schemas/ApiConsent'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - ClientAccessToken: []
  /v1/consents/clients/{clientId}/users/{userId}:
    delete:
      operationId: deleteAppConsents
      summary: Delete consents by user ID
      description: >-
        Delete consents by user ID. If no consent ID is provided, all consents
        for the user are deleted. <br><br>**Required permissions**:
        `apps:delete`, `[appId]:delete`, `consents:delete`.
      parameters:
        - name: clientId
          required: true
          in: path
          description: ID of the client
          schema:
            type: string
        - name: userId
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
        - name: consent_id
          required: false
          in: query
          description: ID of the consent to delete
          schema:
            type: string
      responses:
        '200':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - ClientAccessToken: []
  /v1/manage/consents:
    get:
      operationId: getAllAppConsents
      summary: Get all consents for an app
      description: >-
        Retrieve all consents for an app. <br><br>**Required permissions**:
        `apps:read`, `[appId]:read`, `consents:read`.
      parameters:
        - name: client_id
          required: false
          in: query
          description: >-
            ID of the client whose consents are to be retrieved. If not
            provided, all consents will be retrieved.
          schema:
            type: string
        - name: user_id
          required: false
          in: query
          description: >-
            ID of the user whose consents are to be retrieved. If not provided,
            all consents will be retrieved.
          schema:
            type: string
        - name: app_id
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getAllAppConsents
                type: object
                required:
                  - result
                description: Consent information
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiClientConsent'
      security:
        - ClientAccessToken: []
  /v1/manage/consents/clients/{clientId}/users/{userId}:
    delete:
      operationId: deleteClientConsents
      summary: Delete consents by client ID
      description: >-
        Delete consents by client ID. If no consent ID is provided, all consents
        for the client are deleted. <br><br>**Required permissions**:
        `apps:delete`, `[appId]:delete`, `consents:delete`.
      parameters:
        - name: clientId
          required: true
          in: path
          description: The consent ID to search for
          schema:
            type: string
        - name: userId
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
        - name: consent_id
          required: false
          in: query
          description: ID of the consent to delete
          schema:
            type: string
        - name: app_id
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - ClientAccessToken: []
  /v1/consents/me:
    get:
      operationId: getAllUserConsents
      summary: Get all consents for current user
      description: Get all consents for current user
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getAllUserConsents
                type: object
                required:
                  - result
                description: Consents information
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiConsent'
      security:
        - UserAccessToken: []
  /v1/consents/me/clients/{clientId}:
    delete:
      operationId: deleteUserConsents
      summary: Revoke a consent by ID for current user
      description: Revoke a consent by ID for current user.
      parameters:
        - name: clientId
          required: true
          in: path
          description: ID of the client
          schema:
            type: string
        - name: consent_id
          required: false
          in: query
          description: ID of the consent to delete
          schema:
            type: string
      responses:
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - UserAccessToken: []
components:
  schemas:
    ApiConsent:
      type: object
      properties:
        consent_id:
          type: string
          description: ID of the consent
        tenant_id:
          type: string
          description: ID of the tenant
        app_id:
          type: string
          description: ID of the app
        client_id:
          type: string
          description: ID of the client
        user_id:
          type: string
          description: ID of the user
        scope:
          type: string
          description: Configures the consent scope of the user
        created_at:
          type: number
          description: Date the consent was created in the tenant
        expires_at:
          type: number
          description: Date the consent will be expired
        updated_at:
          type: number
          description: Date the consent will be expired
      required:
        - consent_id
        - tenant_id
        - app_id
        - client_id
        - user_id
        - scope
        - created_at
        - expires_at
        - updated_at
    NotFoundHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
          example: 404
      required:
        - message
        - error_code
    ApiClientConsent:
      type: object
      properties:
        consent_id:
          type: string
          description: ID of the consent
        tenant_id:
          type: string
          description: ID of the tenant
        app_id:
          type: string
          description: ID of the app
        client_id:
          type: string
          description: ID of the client
        user_id:
          type: string
          description: ID of the user
        scope:
          type: string
          description: Configures the consent scope of the user
        created_at:
          type: number
          description: Date the consent was created in the tenant
        expires_at:
          type: number
          description: Date the consent will be expired
        updated_at:
          type: number
          description: Date the consent will be expired
        client_name:
          type: string
          description: Name of the client
      required:
        - consent_id
        - tenant_id
        - app_id
        - client_id
        - user_id
        - scope
        - created_at
        - expires_at
        - updated_at
        - client_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.
