Consent Prototype

openapi: 3.0.0
info:
  title: Consent API
  version: '0.9.1'
  description: |-
    The Consent API is implemented by parties that utilize classification II or IV data services, which require a consent from a school. This API enables the reference component `Consentmanagement` of both parties to exchange a given consent from an Administrator of the School to the other party and setup the exchange of the data service between the two parties.
    
    The endpoints for the Consent API differ for each transaction role and also depends on the supported implementation variants. This API document outlines four different Consent API implementation profiles:
    - **Consent API Bron** for the implementation variants Bron met *Consent API en Afnemer als Consent Consumer* and *Bron en Afnemer met Consent API*
    - **Consent API Afnemer** for the implementation variant *Bron en afnemer met Consent API*.
    - **Consent API Verzender** for the implementation variant *Verzender en Ontvanger met Consent API*
    - **Consent API Ontvanger** for the implementation variants *Verzender als Consent Consumer en Ontvanger met Consent API* and *Verzender en Ontvanger met Consent API*.

    In the consent objects a Data Provider and a Data Consumer are referenced. A consent is always registered at the source of the data, being the Data Provider. In case the transaction protocol is push based, the Data provider sends the data to the Data consumer. For this protocol a consent registration must be confirmed by the Data Consumer.

    **Example 1: SIS API**<br>
    For the SIS API, a party with the reference component `Administratiesysteem onderwijsdeelnemer` is the Data Provider. The reference components `Aanspraakmanager`, `Gebruiksomgeving digitaal leermateriaal`, `Digitaal toetssysteem` or `Leermiddelendashboard` are examples of the Data Consumers.

    **Example 2: Results API**<br>
    For the Results API, the reference component `Digitaal toetssysteem` is the Data Provider. The reference component `Administratiesysteem leerresultaten` is the Data Consumer.

  contact:
    name: Edu-V
    url: www.edu-v.org/afsprakenstelsel
    email: info@edu-v.org
components:
  schemas:
    
    schemaVersion:
      type: string
      description: |
        Schema version of this API using semantic versioning 2.0.0.
        The API version number is communicated in the header.
        The major version is communicated in the URI.
        For more information see the [Edu-V versioning guidelines](https://edu-v.atlassian.net/wiki/spaces/AFSPRAKENS/pages/9437200/Versiebeheer).
      default: 0.9.1
    
    ConsentStatus:
      type: object
      x-tags:
        - Consent
      description: |
        A model that describes the consent registration between 2 reference components. It contains 2 ids and 2 statuses and is valid for an API and scope for a school.
        In the consent both the Data Provider and the Data Consumer are referenced.
      title: ConsentStatus
      properties:
        providerReferenceId:
          type: string
          description: 'Unique reference Id of this consent, as generated by the Data Provider. Example: `Administratiesysteem onderwijsdeelnemer` is Data Provider of SIS-data. Value is empty in case the ConsentRequest has not been confirmed yet.'
        consumerReferenceId:
          type: string
          description: 'Unique reference Id of this consent, as generated by the Data Consumer. Example: `Aanspraakmanager`, `Gebruiksomgeving digitaal leermateriaal`, `Digitaal toetssysteem` or `Leermiddelendashboard` are examples of Data Consumers of SIS-data. Value is empty in case the Consent has not been confirmed yet.'
        school:
          description: 'The School for which consent is registered.'
          $ref: '#/components/schemas/SchoolReference'
        api:
          type: string
          description: 'The API for which consent is registered.'
          enum:
            - students-api
            - employees-api
            - education-api
            - association-api
            - delivery-api
            - entitlement-api
            - usage-api
            - progress-api
            - results-api
        scopes:
          type: array
          items:
            type: string
            description: 'The scopes within the API for which consent is registered.'
            enum:
              - student.basic
              - student.communication
              - student.demographics
              - student.accessibility
              - student.deliveryaddress
              - employee.basic
              - employee.communication
              - employee.roles
              - education
              - association
              - delivery.portal
              - delivery.dashboard
              - entitlement.portal
              - entitlement.dashboard
              - usage.dashboard
              - progress
              - result
        providerStatus:
          type: string
          description: 'The status of the consent for the api and school at the Data Provider.'
          enum:
            - pending
            - accepted
            - declined
            - revoked
        consumerStatus:
          type: string
          description: 'The current status of the consent for the api and school at the Data Consumer.'
          enum:
            - pending
            - accepted
            - declined
            - revoked
      required:
        - providerReferenceId
        - school
        - api
        - scopes
        - providerStatus
    
    ConsentRevoke:
      type: object
      x-tags:
        - Consent
      description: 'A model that describes a consent revoke from the Data Consumer or the Data Provider.'
      title: ConsentRevoke
      properties:
        providerReferenceId:
          type: string
          description: 'Unique reference Id of this consent, as generated by the Data Provider.'
        consumerReferenceId:
          type: string
          description: 'Unique reference Id of this consent, as generated by the Data Consumer.'
        school:
          description: 'The School for which consent is registered.'
          $ref: '#/components/schemas/SchoolReference'
        api:
          type: string
          description: 'The API for which consent is revoked.'
          enum:
            - students-api
            - employees-api
            - education-api
            - association-api
            - delivery-api
            - entitlement-api
            - usage-api
            - progress-api
            - results-api
        scopes:
          type: array
          items:
            type: string
            description: 'The scopes within the API for which consent is revoked.'
            enum:
              - student.basic
              - student.communication
              - student.demographics
              - student.accessibility
              - student.deliveryaddress
              - employee.basic
              - employee.communication
              - employee.roles
              - education
              - association
              - delivery.portal
              - delivery.dashboard
              - entitlement.portal
              - entitlement.dashboard
              - usage.dashboard
              - progress
              - result
        providerStatus:
          type: string
          description: 'The status revoked for the consent registration at the Data Provider.'
          enum:
            - revoked
        consumerStatus:
          type: string
          description: 'The status revoked for the consent registration at the Data Consumer.'
          enum:
            - revoked
      required:
        - providerReferenceId
        - consumerReferenceId
        - school
        - api
        - scopes

    ConsentNotification:
      type: object
      x-tags:
        - Consent
      description: 'A model that describes the consent registration or the approval of a consent request from the Data Provider. The consent notification is send by the Data Provider to the Data Consumer.'
      title: ConsentNotification
      properties:
        providerReferenceId:
          type: string
          description: 'Unique reference Id of this consent, as generated by the Data Provider.'
        consumerReferenceId:
          type: string
          description: 'Unique reference Id of this consent, as generated by the Data Consumer. In case this notification is a reply to an earlier ConsentRequest, the consumerReferenceId from the ConsentRequest is included.'
        school:
          description: 'The School for which consent is registered.'
          $ref: '#/components/schemas/SchoolReference'
        api:
          type: string
          description: 'The API for which consent is registered.'
          enum:
            - students-api
            - employees-api
            - education-api
            - association-api
            - delivery-api
            - entitlement-api
            - usage-api
            - progress-api
            - results-api
        scopes:
          type: array
          items:
            type: string
            description: 'The scopes within the API for which consent is registered.'
            enum:
              - student.basic
              - student.communication
              - student.demographics
              - student.accessibility
              - student.deliveryaddress
              - employee.basic
              - employee.communication
              - employee.roles
              - education
              - association
              - delivery.portal
              - delivery.dashboard
              - entitlement.portal
              - entitlement.dashboard
              - usage.dashboard
              - progress
              - result
        providerStatus:
          type: string
          description: 'The status of the consent registration at the Data Provider.'
          enum:
            - pending
            - accepted
            - declined
      required:
        - providerReferenceId
        - school
        - api
        - scopes
        - providerStatus
    
    ConsentConfirmation:
      type: object
      x-tags:
        - Consent
      description: 'A model that describes the consent confirmation from the Data Consumer to the Data Provider.'
      title: ConsentConfirmation
      properties:
        providerReferenceId:
          type: string
          description: 'Unique reference Id of this consent, as generated by the Data Provider. The Data Consumer received this providerReferenceId from a new ConsentStatus or a ConsentNotification'
        consumerReferenceId:
          type: string
          description: 'Unique reference Id of this consent, as generated by the Data Consumer as a reply to the Data Provider.'
        school:
          description: 'The School for which consent is registered.'
          $ref: '#/components/schemas/SchoolReference'
        api:
          type: string
          description: 'The API for which consent is registered.'
          enum:
            - delivery-api
            - entitlement-api
            - usage-api
            - progress-api
            - results-api
        scopes:
          type: array
          items:
            type: string
            description: 'The scopes within the API for which consent is registered.'
            enum:
              - delivery.portal
              - delivery.dashboard
              - entitlement.portal
              - entitlement.dashboard
              - usage.dashboard
              - progress
              - result
        consumerStatus:
          type: string
          description: 'The status of the consent registration at the Data Consumer.'
          enum:
            - pending
            - accepted
            - declined
            - revoked
      required:
        - providerReferenceId
        - consumerReferenceId
        - school
        - api
        - scopes
        - consumerStatus

    ConsentRequest:
      type: object
      x-tags:
        - Consent
      description: 'A model that describes a consent request from the Data Consumer to the Data Provider.'
      title: ConsentRequest
      properties:
        consumerReferenceId:
          type: string
          description: 'Unique reference Id of this consent request, as generated by the Data Consumer.'
        school:
          description: 'The School for which consent is registered.'
          $ref: '#/components/schemas/SchoolReference'
        api:
          type: string
          description: 'The API for which consent is requested.'
          enum:
            - students-api
            - employees-api
            - education-api
            - association-api
            - delivery-api
            - entitlement-api
            - usage-api
            - progress-api
            - results-api
        scopes:
          type: array
          items:
            type: string
            description: 'The scopes within the API for which consent is requested.'
            enum:
              - student.basic
              - student.communication
              - student.demographics
              - student.accessibility
              - student.deliveryaddress
              - employee.basic
              - employee.communication
              - employee.roles
              - education
              - association
              - delivery.portal
              - delivery.dashboard
              - entitlement.portal
              - entitlement.dashboard
              - usage.dashboard
              - progress
              - result
        consumerStatus:
          type: string
          description: 'The status accepted for the consent registration at the Data Consumer.'
          enum:
            - accepted
      required:
        - consumerReferenceId
        - school
        - api
        - scopes
        - consumerStatus
    
    SchoolReference:
      type: object
      title: SchoolReference
      description: 'A reference to a School organisation.'
      properties:
        organisationMasterIdentifier:
          type: string
          description: |
            The primary identifier for a School. For Schools the `OnderwijsaanbiederId` is used.
            (either organisationMasterIdentifier or organisationIds is required)
          example: '104A158' # De Mariënborn
        organisationIds:
          type: array
          description: |
            A secondary identifier for the School. This value is used whenever the primary identifier is not available.
            (either organisationMasterIdentifier or organisationIds is required)
          items:
            type: object
            properties:
              organisationId:
                type: string
              organisationIdType:
                type: string
                enum:
                  - OIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
                  - BP_ID # Basispoort gegenereerde identifier voor de school.
                  - DD_ID # Door de Centrale Registratie van Edu-iX gegenereerde DigiDeliveryId van de school.
                  - AS_ID # Door het Leerlingadministratiesysteem gegenereerde identifier van de school.
            required:
              - organisationId
              - organisationIdType

    StatusResponse:
      title: StatusResponse
      type: object
      description: 'Functional status code and status message.'
      properties:
        status:
          type: integer
          description: 'See functional status codes within the Documentation.'
        statusMessage:
          type: string
          description: 'See functional status messages within the Documentation.'
      required:
        - status
    
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.example.com/oauth2/token
          refreshUrl: https://api.example.com/oauth2/token
          scopes:
            eduv.consent: 'scope that allows a party to call the Consent API.'

paths:
  
  /consent/statuses:
    parameters:
      - schema:
          type: string
          enum:
            - students-api
            - employees-api
            - education-api
            - association-api
            - delivery-api
            - entitlement-api
            - usage-api
            - progress-api
            - results-api
        name: api
        in: query
        required: false
        description: 'The API for which a party wants to retrieve the Consent status information.'
      - schema:
          type: string
          format: date-time
        in: query
        name: since
        required: false
        description: 'Request all consentstatus information after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
        example: "2017-07-21T17:32:28Z"
    get:
      summary: 'GET ConsentStatuses'
      operationId: get-consent-statuses
      x-tags:
        - Consent
      tags:
        - Consent API Bron
        - Consent API Afnemer
        - Consent API Verzender
        - Consent API Ontvanger
      description: 'Retrieve all consents registered for the requesting party. The consents are registered on the ClientId that is included in the OAuth2.0 token.'
      responses:
        '200':
          description: 'If the api path parameter is empty, the responses includes all apis for which a consent is registered at the Data Provider or the Data Consumer.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsentStatus'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - eduv.consent
  
  /consent/statuses/school:
    parameters:
      - schema:
          type: string
        name: orgMasterId
        in: query
        required: false
        description: |
          The organisationMasterIdentifier of the school.
          This parameter is used when the primary identifier for a school (being the `OnderwijsaanbiederId`) is available.
      - schema:
          type: string
        name: orgId
        in: query
        required: false
        description: |
          The organisationIdentifier (secondary identifier) of the school.
          This parameter is used in combination with the orgIdType when the organisationMasterIdentifier is not available.
      - schema:
          type: string
          example: DD_ID
          enum:
            - OIE_CODE
            - BP_ID
            - DD_ID
            - AS_ID
        name: orgIdType
        in: query
        required: false
        description: |
          The type of the organisationIdentifier.
          This parameter is used in combination with the orgId when the organisationMasterIdentifier is not available.
      - schema:
          type: string
          enum:
            - students-api
            - employees-api
            - education-api
            - association-api
            - delivery-api
            - entitlement-api
            - usage-api
            - progress-api
            - results-api
        name: api
        in: query
        required: false
        description: 'The API for which a party wants to retrieve the Consent status.'
      - schema:
          type: string
          format: date-time
        in: query
        name: since
        required: false
        description: 'Request all consentstatus information after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
        example: "2017-07-21T17:32:28Z"
      - schema:
          type: string
        name: providerReferenceId
        in: query
        required: false
        description: 'Optional providerReferenceId of the Consent registration.'
      - schema:
          type: string
        name: consumerReferenceId
        in: query
        required: false
        description: 'Optional consumerReferenceId of the Consent registration.'
    get:
      summary: 'GET ConsentStatuses by School'
      operationId: get-consent-statuses-by-school
      x-tags:
        - Consent
      tags:
        - Consent API Bron
        - Consent API Afnemer
        - Consent API Verzender
        - Consent API Ontvanger
      description: 'Retrieve the most recent consent registered for a specified `school` and `api`. Alternatively a `providerReferenceId` and/or `consumerReferenceId` can be included in the query to retrieve the status of a specific consent registration.'
      responses:
        '200':
          description: 'In the responses the most recent consent is included for which a consent is registered at the Data Provider or Data Consumer.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsentStatus'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - eduv.consent

  /consent/revokes:
    put:
      summary: 'PUT a ConsentRevoke to Data Provider or Data Consumer'
      operationId: put-consent-revoke
      x-tags:
        - Consent
      tags:
        - Consent API Bron
        - Consent API Afnemer
        - Consent API Verzender
        - Consent API Ontvanger
      description: 'This endpoint is offered by both the Data Provider and the Data Consumer to receive revoke requests for consents.'
      requestBody:
        description: 'Revoke request for a specified consent registration.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentRevoke'
      responses:
        '202':
          description: 'The Consent Revoke is accepted and will be processed.'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - eduv.consent

  /consent/notifications:
    put:
      summary: 'PUT a ConsentNotification to Data Consumer'
      operationId: put-consent-notification
      x-tags:
        - Consent
      tags:
        - Consent API Afnemer
        - Consent API Ontvanger
      description: 'This endpoint is offered by the Data Consumer and allows Data Providers to notify the Data Consumer of a new consent registration.'
      requestBody:
        description: 'Update of consent for a school, api, and scope from the Data Provider.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentNotification'
      responses:
        '202':
          description: 'The ConsentNotification is accepted and will be processed.'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - eduv.consent

  /consent/confirmations:
    put:
      summary: 'PUT a ConsentConfirmation to Data Provider'
      operationId: put-consent-confirmation
      x-tags:
        - Consent
      tags:
        - Consent API Verzender
      description: 'This endpoint is offered by the Data Provider and allows Data Consumers to notify the Data Provider of a new consent confirmation.'
      requestBody:
        description: 'Confirmation of a consent registration for a school, api, and scope from the Data Consumer.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentConfirmation'
      responses:
        '202':
          description: 'The ConsentConfirmation is accepted and will be processed.'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - eduv.consent
    get:
      summary: 'GET ConsentConfirmations from Data Consumer after a specified timestamp'
      operationId: get-consent-confirmations
      x-tags:
        - Consent
      tags:
        - Consent API Ontvanger
      description: 'Retrieve all consent confirmations for the requesting party after a specified timestamp. The consent confirmations are registered on the ClientId that is included in the OAuth2.0 token.'
      parameters:
        - schema:
            type: string
            enum:
            - students-api
            - employees-api
            - education-api
            - association-api
            - delivery-api
            - entitlement-api
            - usage-api
            - progress-api
            - results-api
          name: api
          in: query
          required: false
          description: 'The API for which a party wants to retrieve the Consent Requests information.'
        - schema:
            type: string
            format: date-time
          in: query
          name: since
          required: false
          description: 'Request all consent confirmation information after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
          example: "2017-07-21T17:32:28Z"
      responses:
        '200':
          description: 'If the api path parameter is empty, the responses includes all apis for which a consent is confirmed at the Data Consumer.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsentConfirmation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - eduv.consent

  /consent/requests:
    put:
      summary: 'PUT a ConsentRequest to Data Provider'
      operationId: put-consent-request
      x-tags:
        - Consent
      tags:
        - Consent API Bron
        - Consent API Verzender
      description: 'This endpoint is offered by the Data Provider to receive consent requests.'
      requestBody:
        description: 'Request for a specified consent registration.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentRequest'
      responses:
        '202':
          description: 'The Consent Request is accepted and will be processed.'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - eduv.consent
    get:
      summary: 'GET ConsentRequests from Data Consumer after a specified timestamp'
      operationId: get-consent-requests
      x-tags:
        - Consent
      tags:
        - Consent API Ontvanger
      description: 'This endpoint is offered by the Data Consumer to request all given consent requests.'
      parameters:
        - schema:
            type: string
            enum:
            - students-api
            - employees-api
            - education-api
            - association-api
            - delivery-api
            - entitlement-api
            - usage-api
            - progress-api
            - results-api
          name: api
          in: query
          required: false
          description: 'The API for which a party wants to retrieve the Consent Requests information.'
        - schema:
            type: string
            format: date-time
          in: query
          name: since
          required: false
          description: 'Request all consent requests information after the specified timestamp. Format: Conform openapi in ZULU time as specified in RFC 3339, section 5.6'
          example: "2017-07-21T17:32:28Z"
      responses:
        '200':
          description: 'If the api path parameter is empty, the responses includes all apis for which consent requests are registered at the Data Consumer.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsentRequest'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - OAuth2:
            - eduv.consent
    
  x-tags:
    - Consent