Akoya Consent API OpenAPI specification

By hovering on the code, a clipboard icon will appear on the top right. Use it to copy the code. Then paste into your favorite text or code editor and save as a YAML file.
openapi: 3.1.0
x-stoplight:
  id: i0hxd27c1n9m0
info:
  title: Akoya Consent API v1.1.0
  version: 1.1.0
  contact:
    name: Akoya
    url: 'https://www.akoya.com/'
    email: [email protected]
  license:
    name: Akoya Terms of Use
    url: 'https://recipient.ddp.akoya.com/terms-of-use'
  description: "Use this endpoint to get the details of an end-user's consent.\r\n\r\n**Updates**\r\n\r\n- v1.1.0\r\n    - February 11, 2025\r\n        - Bugfixes - removed body params\r\n        - Added sample responses\r\n    - October 31, 2024\r\n        - Updated response payload.\r\n- v1.0.2\r\n    - August 30, 2024\r\n        - Added sandbox server.\r\n        - Added notification banners.\r\n- v1.0.1\r\n    - July 29, 2024\r\n        - Added a request body to the Get Consent Grant endpoint.\r\n        - Corrected description text for the Get Consent Grant endpoint."
servers:
  - url: 'https://sandbox-api.akoya.com'
    description: Sandbox Consent API server
  - url: 'https://api.akoya.com'
    description: Consent API server
tags:
  - name: Consent API
    description: Manage end-user consent
security:
  - bearerAuth: []
paths:
  '/consents/{version}/{consentId}':
    parameters:
      - $ref: '#/components/parameters/consentId'
      - $ref: '#/components/parameters/version'
    get:
      summary: Get Consent Grant
      tags:
        - Consent API
      operationId: get-consent-grant
      description: "Use this endpoint to get the details of an end-user's consent.\r\n\r\nYou may use the Consent API to receive notifications of an end-user's change in consent. If you haven't already, subscribe to receive notifications.\r\nYou'll receive a notification via webhook if your user changes their consent through their provider's website or interface. To see a list of the providers which support consent notifications, log in to the *Data Recipient Hub* Support Center. Then, view the [consent notification providers](https://recipient.ddp.akoya.com/support/article/kA0Uw0000000OS9KAM) list. \r\n\r\n\r\n> \U0001F4D8 Note\r\n>\r\n> This endpoint is supported in sandbox (`https://sandbox-api.akoya.com`) and production (`https://api.akoya.com`)\r\n\r\n> \U0001F6D1 The *service token* should be used as the bearer token with this call."
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  parties:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        type:
                          type: string
                        registeredEntityId:
                          type: string
                  createdTime:
                    type: string
                  resources:
                    type: array
                    items:
                      type: object
                      properties:
                        resourceType:
                          type: string
                        resourceId:
                          type: string
                        dataClusters:
                          type: array
                          items:
                            type: string
                x-examples:
                  Example 1:
                    id: dfb491d5-599e-413f-8957-ae889732d2b6
                    status: ACTIVE
                    parties:
                      - name: Mikomo
                        type: DATA_PROVIDER
                        registeredEntityId: mikomo
                      - name: Akoya
                        type: DATA_ACCESS_PLATFORM
                        registeredEntityId: akoya
                      - name: Paprika LLC
                        type: DATA_RECIPIENT
                        registeredEntityId: paprika_rec
                      - name: Paprika App
                        type: DATA_RECIPIENT
                        registeredEntityId: paprika
                    createdTime: '2024-02-15T14:19:41.346046Z'
                    resources:
                      - resourceType: ACCOUNT
                        resourceId: '1239098123'
                        dataClusters:
                          - balances
                          - customers
                          - statements
                          - account_info
                          - transactions
                          - investments
                          - payments
              examples:
                Successful Response:
                  value:
                    id: dfb491d5-599e-413f-8957-ae889732d2b6
                    status: ACTIVE
                    parties:
                      - name: Mikomo
                        type: DATA_PROVIDER
                        registeredEntityId: mikomo
                      - name: Akoya
                        type: DATA_ACCESS_PLATFORM
                        registeredEntityId: akoya
                      - name: Paprika LLC
                        type: DATA_RECIPIENT
                        registeredEntityId: paprika_rec
                      - name: Paprika App
                        type: DATA_RECIPIENT
                        registeredEntityId: paprika
                    createdTime: '2024-02-15T14:19:41.346046Z'
                    resources:
                      - resourceType: ACCOUNT
                        resourceId: '1239098123'
                        dataClusters:
                          - balances
                          - customers
                          - statements
                          - account_info
                          - transactions
                          - investments
                          - payments
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
                x-examples:
                  Example 1:
                    code: 401
                    message: Invalid input
              examples:
                Bad Request:
                  value:
                    code: 401
                    message: Invalid input
        '404':
          description: Unknown grant ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                x-examples:
                  Example 1:
                    code: NotFound
                    message: resource not found
              examples:
                Unknown Grant ID:
                  value:
                    code: NotFound
                    message: resource not found
        '405':
          description: Method Not Allowed
          content:
            text/plain:
              schema:
                type: string
              examples:
                Method not Allowed:
                  value: Method Not Allowed
        '500':
          description: Catch all exception where request was not processed due to an internal outage/issue.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  debugMessage:
                    type: string
                x-examples:
                  Example 1:
                    code: '500'
                    message: Internal server error
                    debugMessage: Provider custom developer-level error details for troubleshooting
              examples:
                Internal Server Error:
                  value:
                    code: '500'
                    message: Internal server error
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '501':
          description: FDX version not supported or implemented.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  debugMessage:
                    type: string
                x-examples:
                  Example 1:
                    code: '1106'
                    message: FdxVersion not supported or not implemented
                    debugMessage: Provider custom developer-level error details for troubleshooting
              examples:
                FDX Version not Supported or Implemented:
                  value:
                    code: '1106'
                    message: FdxVersion not supported or not implemented
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  debugMessage:
                    type: string
                x-examples:
                  Example 1:
                    code: '503'
                    message: Scheduled Maintenance
                    debugMessage: Provider custom developer-level error details for troubleshooting
              examples:
                Scheduled Maintenance:
                  value:
                    code: '503'
                    message: Scheduled Maintenance
                    debugMessage: Provider custom developer-level error details for troubleshooting
      x-stoplight:
        id: snrjur1c5zlp6
components:
  parameters:
    version:
      name: version
      in: path
      required: true
      schema:
        type: string
        default: v1
        enum:
          - v1
      description: version of endpoint
    consentId:
      name: consentId
      in: path
      required: true
      schema:
        type: string
      description: 'Consent Id, may be returned in a notification.'
  securitySchemes:
    bearerAuth:
      description: Your service token should be used in the header of this call.
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ConsentGrant:
      title: Consent Grant entity
      description: Record of user consent
      type: object
      properties:
        id:
          description: The persistent identifier of the consent
          type: string
          maxLength: 256
        status:
          description: The current status of the consent
          type: string
          enum:
            - ACTIVE
            - EXPIRED
            - REVOKED
        parties:
          description: The non-end user parties participating in the Consent Grant
          type: array
          items:
            $ref: '#/components/schemas/ConsentGrantParty'
        createdTime:
          description: When the consent was initially granted
          type: string
          format: date-time
          example: '2021-07-15T14:46:41.375Z'
        resources:
          description: The permissioned resource entities
          type: array
          items:
            $ref: '#/components/schemas/ConsentGrantResource'
      x-stoplight:
        id: xys57l43qns5l
    ConsentGrantParty:
      title: Consent Grant Party entity
      description: 'Details on the non-end user parties in the Consent Grant. Includes the legal entity operating branded products or services in the data sharing chain. Descriptive information is collected during Data Recipient registration at Data Provider, and populated during issuance by Data Provider from its registry'
      type: object
      allOf:
        - $ref: '#/components/schemas/Party'
      required:
        - registeredEntityId
      x-stoplight:
        id: cdm7cw9fsrxi2
    ConsentGrantResource:
      title: Consent Grant Resource entity
      description: Entity of permissioned resources
      type: object
      properties:
        resourceType:
          description: Type of resource to be permissioned
          type: string
          enum:
            - ACCOUNT
            - CUSTOMER
            - DOCUMENT
        resourceId:
          description: Identifier of resource to be permissioned
          type: string
          maxLength: 256
        dataClusters:
          description: Names of clusters of data elements permissioned
          type: array
          items:
            $ref: '#/components/schemas/DataCluster'
          minItems: 1
      required:
        - resourceType
        - resourceId
        - dataClusters
      x-stoplight:
        id: r4p8o5gkr0j92
    DataCluster:
      title: Data Cluster
      description: Name of permissioned Data Cluster. For Data Cluster definitions refer to the Consent Components > Data Clusters section of the User Experience Guidelines document included in the FDX API
      type: string
      enum:
        - account_info
        - balances
        - customers
        - investments
        - payments
        - statements
        - transactions
      x-stoplight:
        id: yso1gnqa4lxlb
    Party:
      title: Party entity
      description: FDX Participant - an entity or person that is a part of a FDX API transaction
      type: object
      required:
        - name
        - type
      properties:
        name:
          description: Human recognizable common name
          type: string
        type:
          description: Extensible string enum identifying the type of the party
          type: string
          enum:
            - DATA_ACCESS_PLATFORM
            - DATA_PROVIDER
            - DATA_RECIPIENT
            - INDIVIDUAL
            - MERCHANT
            - VENDOR
        registeredEntityId:
          description: Registered id of party
          type: string
      x-stoplight:
        id: 7p34vib8ko76l
x-internal: true
Change log

Date	Update
2024-Dec-10	Updated to v1.1.0
2024-Sept-09	Original
Need help?

Check out our Developer Community, or visit the Support Center in the Data Recipient Hub.
Looking for provider nuance documentation?

All provider nuance documentation is available in the Data providers section in the Data Recipient Hub.
Still stuck?

For all production issues, submit a support ticket through the Data Recipient Hub. Our support team is standing by 24/7. Questions and non-production issues will be answered during business hours.