Akoya Consent API OpenAPI specification

openapi: 3.1.0
x-stoplight:
  id: xvjooohdzq6bb
info:
  title: Akoya Consent API v1.0.2
  version: 1.0.2
  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\nConsent API v1 updates\r\n- August 30, 2024\r\n    - v1.0.2\r\n        - Added sandbox server.\r\n        - Added notification banners.\r\n- July 29, 2024\r\n    - v1.0.1\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:
                $ref: '#/components/schemas/ConsentGrant'
              examples:
                Example 1:
                  value:
                    id: dfb491d5-599e-413f-8957-ae889732d2b6
                    status: ACTIVE
                    parties:
                      - name: Mikomo
                        type: DATA_PROVIDER
                        registeredEntityId: mikomo
                      - name: Paprika
                        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
      x-stoplight:
        id: yf03gsvcv1ciu
      requestBody:
        description: Set the `grant_type` and `scope`.
        content:
          application/json:
            schema:
              type: object
              x-examples:
                Example 1:
                  grant_type: client credentials
                  scope: notifications_subscriptions advisory
              required:
                - grant_type
                - scope
              properties:
                grant_type:
                  description: 'Defaults to client_credentials, your `clientId` and `clientSecret`.'
                  example: client_credentials
                  enum:
                    - client_credentials
                scope:
                  description: The Akoya service accessed by provided credentials.
                  enum:
                    - notifications_subscriptions advisory
            examples:
              Example 1:
                value:
                  grant_type: client_credentials
                  scope: notifications_subscriptions advisory
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: kbl3095m5zthn
    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: lsl0vrt5wamgz
    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: isuvrg1wctihe
    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: fsle4m0agwnil
    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: 57vffdiz1ip39
x-internal: true