openapi: 3.2.0
info:
  title: V4 Consent Management API
  version: '4.0'
  contact:
    name: MX
    url: https://www.mx.com
  description: API for embedding the consent management dashboard into your customer-facing experience.
  termsOfService: https://www.mx.com/terms/
servers:
- url: http://{baseurl}
security:
- basicAuth: []
tags:
- name: consent_management
  description: Consent Management
paths:
  /api/{version}/consent_management:
    get:
      tags:
      - consent_management
      summary: Consent list
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentList'
      operationId: 3-consentList
      description: Returns all data sharing information for an end user. Use this endpoint to list an end user's current data sharing choices. Each of the end user's connected apps has a separate consent which is detailed in the response by a consent object. The consent object includes details such as the app's id, name, icon, and the sharing status of the end-user's accounts.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/version'
  /api/{version}/consent_management/{ConsentPublicId}/accounts:
    parameters:
    - $ref: '#/components/parameters/ConsentPublicId'
    - $ref: '#/components/parameters/version'
    put:
      tags:
      - consent_management
      summary: Update Auto Access
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - automatic_access
              properties:
                automatic_access:
                  type: boolean
                  example: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Consent'
      operationId: autoAccessUpdate
      description: Set a consented app's auto update status. Use this endpoint to allow or disallow an app to automatically add new accounts to an end user's consent. This sets the consent object's `auto_enable_future_accounts` field to true or false.
      security:
      - bearerAuth: []
  /api/{version}/consent_management/{ConsentPublicId}/accounts/{AccountId}:
    put:
      tags:
      - consent_management
      summary: Update Consented Account
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
              required:
              - enabled
              x-examples:
                Example 1:
                  enabled: true
      parameters:
      - $ref: '#/components/parameters/ConsentPublicId'
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/version'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Consent'
      operationId: accountEnabledStatus
      description: Updates a consent by enabling or disabling an account. Use this endpoint when an end user wants to change whether or not an account is shared with an app.
      security:
      - bearerAuth: []
  /api/{version}/consent_management/{ConsentPublicId}/disable_app_sharing:
    put:
      tags:
      - consent_management
      summary: Revoke Consent
      parameters:
      - $ref: '#/components/parameters/ConsentPublicId'
      - $ref: '#/components/parameters/version'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Consent'
      operationId: revokeConsent
      security:
      - bearerAuth: []
      description: Disables the selected consent and updates `revoked_at` with current time. Use this endpoint when an end user wants to stop all data sharing with an app.
components:
  schemas:
    Consent:
      type: object
      properties:
        id:
          type: string
          example: _sadfa3CKHJ23LKJHKJHLlNaODPmH1LqSb4
        application_name:
          type: string
          example: Centz
        application_icon_url:
          type:
          - string
          - 'null'
          example: https://www.example.com
        created_at:
          type: string
          example: '2024-06-14T19:48:18.354Z'
        last_accessed:
          type: string
          example: '2024-05-14T19:48:31.352Z'
        accounts:
          type: array
          items:
            type: object
            properties:
              enabled:
                type: boolean
                example: true
              nickname:
                type: string
                example: Lacrosse Fund
              account_id:
                type: string
                example: '1234123412341234'
              account_number_display:
                type: string
                example: XXXXXXXX1111
        auto_enable_future_accounts:
          type: boolean
          example: true
        consented_on:
          type: string
          example: '2024-05-14T19:48:18.352Z'
        revoked_at:
          type:
          - string
          - 'null'
          example: null
      description: Consent object
    ConsentList:
      title: ConsentList
      type: array
      items:
        $ref: '#/components/schemas/Consent'
  parameters:
    ConsentPublicId:
      name: ConsentPublicId
      in: path
      required: true
      schema:
        type: string
      description: The consent id. This value is returned in the GET Consent List as `id`.
    version:
      name: version
      in: path
      required: true
      schema:
        type: string
        default: v4
        example: v4
      description: API version. Indicates which FDX version is in use.
    AccountId:
      name: AccountId
      in: path
      required: true
      schema:
        type: string
      description: The account id selected for update.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    basicAuth:
      type: http
      scheme: basic