knowgo-consent-api.yaml

---
openapi: 3.0.0
info:
  title: KnowGo Consent Management API
  description: The KnowGo Consent Management API, implementing the Kantara Initiative Consent Receipt Specification.
  contact:
    name: Adaptant Labs
    email: labs@adaptant.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.0.1
servers:
- url: https://virtserver.swaggerhub.com/KnowGo/knowgo-consent-api/0.0.1
  description: SwaggerHub API Auto Mocking
- url: https://api.knowgo.io/v1
  description: Production instance
tags:
- name: consent
  description: Consent Receipt Management
- name: categories
  description: Data Categories
- name: purposes
  description: Data Processing Purposes
paths:
  /consents/categories:
    get:
      tags:
      - categories
      summary: List supported data categories
      responses:
        "200":
          description: A JSON array of category types
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /consents/categories/{categoryId}:
    get:
      tags:
      - categories
      summary: Get information about a specific data category
      parameters:
      - name: categoryId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          description: ID number of data category
      responses:
        "200":
          description: A JSON object detailing the Data Category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataCategoryDetail'
  /consents/introspect:
    post:
      tags:
      - consent
      summary: Introspect a consent token
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Token'
      responses:
        "200":
          description: Token valid
        "401":
          description: Unauthorized
        "400":
          description: Invalid token specification
        "404":
          description: Consent not found
  /consents/purposes:
    get:
      tags:
      - purposes
      summary: List supported purposes of processing
      responses:
        "200":
          description: A JSON array of processing purposes
          content:
            aplication/json:
              schema:
                type: array
                items:
                  type: string
  /consents/purposes/{purposeId}:
    get:
      tags:
      - purposes
      summary: Get information about a specific purpose of processing
      parameters:
      - name: purposeId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          description: ID number of processing purpose
      responses:
        "200":
          description: A JSON object detailing the Purpose of Processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurposeDetail'
  /consents:
    get:
      tags:
      - consent
      summary: List all consent receipts
      operationId: listConsentReceipts
      responses:
        "200":
          description: List of consent receipts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsentReceiptDetail'
    post:
      tags:
      - consent
      summary: Add a new consent receipt
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentReceipt'
        required: true
      responses:
        "201":
          description: Consent receipt successfully added
        "401":
          description: Unauthorized
  /consents/receipts/{receiptId}:
    get:
      tags:
      - consent
      summary: Fetch a consent receipt
      operationId: getConsentReceipt
      parameters:
      - name: receiptId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          description: Consent Receipt ID
          format: uuid
      responses:
        "200":
          description: A JSON-encoded consent receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentReceipt'
    delete:
      tags:
      - consent
      summary: Revoke consent
      operationId: revokeConsentReceipt
      parameters:
      - name: receiptId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          description: Consent Receipt ID
          format: uuid
      responses:
        "200":
          description: Consent successfully revoked
        "401":
          description: Unauthorized
  /consents/receipts/{receiptId}/supersede/{newReceiptId}:
    post:
      tags:
      - consent
      summary: Replace a consent receipt with a newer consent
      operationId: updateConsentReceipt
      parameters:
      - name: receiptId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          description: Consent Receipt ID
          format: uuid
      - name: newReceiptId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          description: Replacement Consent Receipt ID
          format: uuid
      responses:
        "200":
          description: Consent receipt successfully superseded
        "401":
          description: Unauthorized
        "404":
          description: Invalid consent receipt specification
  /consents/receipts/{receiptId}/token:
    get:
      tags:
      - consent
      summary: Fetch a consent receipt token
      operationId: getConsentReceiptToken
      parameters:
      - name: receiptId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          description: Consent Receipt ID
          format: uuid
      responses:
        "200":
          description: Consent token successfully generated
        "401":
          description: Unauthorized
components:
  schemas:
    ConsentReceipt:
      type: object
      required:
        - version
        - jurisdiction
        - collectionMethod
        - consentReceiptId
        - piiPrincipalId
        - piiControllers
        - policyUrl
        - services
        - sensitive
      properties:
        version:
          type: string
          description: |
            The version of the Kantara CR specification that the receipt
            conforms to.
          example: 'KI-CR-v1.1.0'
          enum:
            - 'KI-CR-v1.1.0'
        jurisdiction:
          type: string
          description: |
            The legal jurisdiction(s) under which the processing of personal
            data occurs, in ISO 3166-1 alpha-2 2-character country code format.
            May be a single jurisdiction, or a list of possible ones separated
            by a space.
          example: 'DE AT IT'
        consentTimestamp:
          type: integer
          format: int64
          description: |
            Timestamp of when consent was issued, in seconds since the UNIX
            epoch.
          example: 1635752562
        collectionMethod:
          type: string
          description: Method of collection describing how consent was obtained
          example: "web sign-up form"
        consentReceiptId:
          type: string
          description: Consent Receipt ID
          format: uuid
          example: '81b5986c-dd92-4fef-b83e-2bc013334610'
        publicKey:
          type: string
          description: The data controller's public key.
        language:
          type: string
          description: |
            Language in which the consent was obtained. MUST use ISO
            639-1:2002 if this field is used.
        piiPrincipalId:
          type: string
          description: |
            PII Principal-provided identifier, such as a user name, email
            address, or claim.
        piiControllers:
          type: array
          items:
            $ref: '#/components/schemas/DataController'
        policyUrl:
          type: string
          format: uri
          description: |
            Privacy policy URL of the service referred to by the receipt.
          example: 'https://example.com/privacy-policy/'
        services:
          type: array
          description: |
            A service or group of services for which PII is being collected,
            together with service-specific purposes of processing.
          items:
            $ref: '#/components/schemas/Service'
        sensitive:
          type: boolean
          description: |
            Indicates whether the consent interaction contains PII that is
            designated as sensitive.
        spiCat:
          type: array
          items:
            type: string
            description: List of sensitive or special-category data categories
            example: '2 - Biometric'
    ConsentReceiptDetail:
      properties:
        consentReceiptId:
          type: string
          description: Consent Receipt ID
          format: uuid
          example: '81b5986c-dd92-4fef-b83e-2bc013334610'
        status:
          $ref: '#/components/schemas/ConsentStatus'
    ConsentStatus:
      type: string
      description: Possible consent states
      enum:
        - ACTIVE
        - REVOKED
        - SUPERSEDED
        - EXPIRED
    ConsentType:
      type: string
      description: Possible consent types
      enum:
        - EXPLICIT
        - IMPLICIT
        - N/A
    DataCategory:
      type: string
      enum:
        - Biographical
        - Contact
        - Biometric
        - SocialContact
        - NetworkService
        - Health
        - Financial
        - OfficialID
        - SocialBenefitData
        - JudicialData
        - AssetData
        - HRData
        - MentalHealth
        - Membership
        - Behavioral
        - Profiling
    DataCategoryDetail:
      properties:
        categoryId:
          type: integer
          description: ID of data category
        category:
          $ref: '#/components/schemas/DataCategory'
    DataController:
      type: object
      required:
        - piiController
        - onBehalf
        - contact
        - address
        - email
        - phone
      properties:
        piiController:
          type: string
          description: Legal name of the first controller who collects the data
        onBehalf:
          type: boolean
          description: |
            Data processor working on behalf of a data controller or other data
            processor.
        contact:
          type: string
          description: Contact name of the controller
        address:
          $ref: '#/components/schemas/PostalAddress'
        email:
          type: string
          format: email
          description: An email address at which the controller can be reached
        phone:
          type: string
          description: A phone number at which the controller can be reached
        piiControllerURL:
          type: string
          format: uri
          description: An optional URL for the controller's website
    PostalAddress:
      type: object
      description: |
        The postal address at which a data controller or processor can be
        reached.
      required:
        - addressCountry
        - addressLocality
        - postalCode
        - streetAddress
      properties:
        addressCountry:
          type: string
        addressLocality:
          type: string
        addressRegion:
          type: string
        postOfficeBoxNumber:
          type: string
        postalCode:
          type: string
        streetAddress:
          type: string
    PurposeDetail:
      properties:
        purposeId:
          type: integer
          description: ID of processing purpose
        purpose:
          type: string
          description: Name of purpose
        description:
          type: string
          description: Description of purpose
    PurposeModel:
      type: object
      required:
        - purpose
        - purposeCategory
        - consentType
        - piiCategory
        - primaryPurpose
        - termination
        - thirdPartyDisclosure
      properties:
        purpose:
          type: string
        purposeCategory:
          $ref: '#/components/schemas/PurposeSpecification'
        consentType:
          $ref: '#/components/schemas/ConsentType'
        piiCategory:
          $ref: '#/components/schemas/DataCategory'
        primaryPurpose:
          type: boolean
        termination:
          type: string
        thirdPartyDisclosure:
          type: boolean
        thirdPartyName:
          type: string
    PurposeSpecification:
      type: string
      enum:
        - CoreFunction
        - ContractedService
        - Delivery
        - ContactRequested
        - PersonalizedExperience
        - Marketing
        - MarketingThirdParties
        - SharingForDelivery
        - SharingForMarketing
        - ThirdPartySharingForCoreFunction
        - ThirdPartySharingForOthers
        - LegallyRequiredDataRetention
        - RequiredByLawEnforcementOrGovernment
        - ProtectingYourHealth
        - ProtectingOurInterests
        - ImprovePerformance
    Service:
      type: object
      required:
        - service
        - purposes
      properties:
        service:
          type: string
          description: Service identifier
        purposes:
          type: array
          items:
            $ref: '#/components/schemas/PurposeModel'
    Token:
      required:
      - token
      type: object
      properties:
        token:
          type: string
  parameters:
    receiptId:
      name: receiptId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type: string
        description: Consent Receipt ID
        format: uuid
    newReceiptId:
      name: newReceiptId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type: string
        description: Replacement Consent Receipt ID
        format: uuid
    categoryId:
      name: categoryId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type: integer
        description: ID number of data category
    purposeId:
      name: purposeId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type: integer
        description: ID number of processing purpose