cdoc2-auth-server-openapi.yaml

openapi: 3.1.0
info:
  contact:
    url: http://ria.ee
  title: cdoc2-auth-server
  version: 0.9.5-draft
  description: |
    API for the session creation process for MID/SID CDOC

servers:
  - url: 'https://localhost:8443'
    description: Regular TLS (no mutual TLS required).

paths:
  '/auth/start':
    post:
      summary: Start auth
      description: Start auth process
      tags:
        - cdoc2-auth
      operationId: startAuth
      responses:
        '201':
          description: Created
          headers:
            Location:
              schema:
                type: string
              description: 'URI of created resource. Auth process UUID can be extracted from URI as
               it follows pattern /auth/status/{authProcessUuid}'
              example: '/auth/status/9a7c3717d21f5cf19d18fa4fa5adee21'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartAuthProcessResponse'
        '400':
          description: 'Bad request. Client error.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthIdentity'


  '/auth/status/{authProcessUuid}':
    get:
      summary: Get auth process status
      description: Get auth process status. When status is COMPLETE will also return the session
        token and signing certificate.
      tags:
        - cdoc2-auth
      operationId: getAuthProcessStatus
      parameters:
        - name: authProcessUuid
          in: path
          schema:
            type: string
            minLength: 18
            maxLength: 36
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProcessStatusResponse'
        '400':
          description: 'Bad request. Client error.'
        '401':
          description: 'Unauthorized. No correct auth headers'
        '404':
          description: 'Not Found. 404 is returned when no auth process is found for UUID'

  '/.well-known/jwks.jws':
    get:
      summary: Returns information about signing keys
      description: Returns information about signing keys
      tags:
        - cdoc2-auth
      operationId: getWellKnown
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WellKnownResponse'
        '400':
          description: 'Bad request. Client error.'
        '403':
          description: 'Authentication failed'

  '/info':
    get:
      summary: Get server info
      description: Returns information about the server.
      operationId: getInfo
      tags:
        - cdoc2-auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              examples:
                Server info example:
                  value:
                    build:
                      artifact: cdoc2-auth-server-webapp
                      name: cdoc2-auth-server-webapp
                      time: '2026-05-29T07:21:23.869Z'
                      version: 0.6.0
                      group: ee.cyber.cdoc2
                    system.time: '2026-05-29T07:22:50Z'

components:
  schemas:
    AuthIdentity:
      title: Auth identity
      type: object
      properties:
        identifier:
          type: string
          minLength: 12
          maxLength: 32
          description: |
            ETSI319412-1. Example "etsi/PNOEE-48010010101".  
            [etsi/:semantics-identifier](https://github.com/SK-EID/smart-id-documentation/blob/v2/README.md#2322-etsisemantics-identifier)
        mobileNr:
          type: string
          minLength: 6
          maxLength: 32
          description: |
            Mobile phone nr
        language:
          type: string
          minLength: 2
          maxLength: 2
          description: |
            Language for user-facing messages (e.g. Mobile-ID/Smart-ID prompts).
            Follows ISO 639-1 standard
      required:
        - identifier

    StartAuthProcessResponse:
      title: Start auth process response
      type: object
      properties:
        vc:
          type: string
          minLength: 4
          maxLength: 4
          description: 'SmartId verification code'
          example: '5702'
      required:
        - vc

    AuthProcessStatusResponse:
      title: Auth process status response
      type: object
      properties:
        status:
          type: string
          enum:
            - STARTED
            - FAILED
            - COMPLETE
          description: 'auth process status'
        endResult:
          type: string
          maxLength: 60
          description: 'End result of SID/MID auth session'
          nullable: true
          example: "OK"
        sessionToken:
          type: string
          description: 'base64url encoded SD-JWT with all disclosures'
          nullable: true
        signingCertificate:
          type: string
          description: 'base64url encoded X509 certificate'
          nullable: true
      required:
        - status

    WellKnownResponse:
      title: well-known response
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          items:
            type: object
            required:
              - kid
              - kty
            properties:
              kid:
                description: 'key identifier'
                example: '1'
                type: string
              kty:
                type: string
                description: 'identifies the cryptographic algorithm family used with the key'
                example: 'EC'
              use:
                type: string
                description: 'identifies the intended use of the public key'
                example: 'enc'
                nullable: true
              crv:
                type: string
                description: 'curve'
                example: 'P-256'
                nullable: true
              x:
                type: string
                description: 'base64 encoded x curve coordinate'
                example: ''
                nullable: true
              y:
                type: string
                description: 'base64 encoded y curve coordinate'
                example: ''
                nullable: true
              n:
                type: string
                description: 'base64 encoded public modulus'
                example: ''
                nullable: true
              e:
                type: string
                description: 'base64 encoded public exponent'
                example: ''
                nullable: true
              alg:
                type: string
                description: 'identifies the algorithm intended for use with the key'
                example: 'RS256'
                nullable: true

  securitySchemes:
    bearerAuth: # long-term token
      type: http
      scheme: bearer
    basicAuth: # temporary solution
      type: http
      scheme: basic

tags:
  - name: cdoc2-auth