nuts-foundation/nuts-node

openapi: "3.0.0"
info:
  title: EmployeeIdentity Means
  description: |
    This specification describes the internal HTTP API for the EmployeeIdentity means.
    Note: It MUST not be used to generate code outside of the Nuts Node since it is an internal service.
  version: 1.0.0
servers:
  - url: http://localhost:1323
paths:
  /public/auth/v1/means/employeeid/{sessionID}/done:
    parameters:
      - name: sessionID
        description: The session ID
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - EmployeeIdentity
      operationId: renderEmployeeIDDonePage
      summary: Render the employee ID done page
      responses:
        '200':
          description: Returns the rendered employee ID done page.
          content:
            text/html:
              schema:
                type: string

  /public/auth/v1/means/employeeid/{sessionID}:
    parameters:
      - name: sessionID
        description: The session ID
        in: path
        required: true
        schema:
          type: string
      - name: headless
        description: If true, the page will be rendered without the header and footer. This is useful for embedding the page in an iframe.
        in: query
        required: false
        schema:
          type: boolean
          default: false
    get:
      tags:
        - EmployeeIdentity
      operationId: renderEmployeeIDPage
      summary: Render the employee ID page
      description: |
        Render the employee ID page
        
        Errors returned:
        * 404 - session could not be found
      responses:
        '200':
          description: Returns the rendered employee ID page containing the form, the challenge and set of buttons to either sign or cancel the session.
          content:
            text/html:
              schema:
                type: string
        '404':
          description: Session could not be found. The session may have expired or does not exist.
          content:
            text/html:
              schema:
                type: string
    post:
      tags:
        - EmployeeIdentity
      operationId: handleEmployeeIDForm
      summary: Handle the employee ID form.
      description: |
        The employee will decide to either confirm its identity and sign the contract or cancel the session.
        This endpoint handles the form submission and returns the appropriate response.
        
        Errors returned:
        * 404 - session could not be found
        * 400 - form could not be parsed
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/EmployeeIDForm"
      responses:
        '302':
          description: The form was successfully parsed and the challenge signed.
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Form could not be parsed.
          content:
            text/html:
              schema:
                type: string
        '404':
          description: Session could not be found. The session may have expired or does not exist.
          content:
            text/html:
              schema:
                type: string

components:
  schemas:
    EmployeeIDForm:
      type: object
      required:
        - choice
        - secret
      properties:
        choice:
          type: string
          enum: [confirm, cancel]
          description: The choice of the user to either confirm or cancel the signing of the contract.
          example: "confirm"
          default: cancel
        secret:
          type: string
          description: The secret for this signing session.
          example: "123456"