cdoc2-rp-server-openapi.yaml

openapi: 3.1.0
info:
  contact:
    url: http://ria.ee
  title: cdoc2-rp-server
  version: 0.9.2-draft
  description: |
    API for RP mediation process and session creation for MID/SID CDOC

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

paths:
  '/session_nonce':
    post:
      summary: Generates session nonce.
      description: |
        Returns a randomly generated nonce value and stores this value in the database for 24 hours.
        Used by cdoc2-auth-server to construct the session token.
      tags:
        - cdoc2-rp
      operationId: getSessionNonce
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NonceResponse'
        '400':
          description: 'Bad request. Client error.'
        '403':
          description: 'Authentication failed'

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

  '/mid/authenticate':
    post:
      summary: Sends authentication request to MID
      description: |
        Sends authentication request to Mobile-ID
      tags:
        - cdoc2-rp
      operationId: midAuthenticate
      parameters:
        - $ref: '#/components/parameters/SessionTokenHeader'
        - $ref: '#/components/parameters/SessionX5cHeader'
      requestBody:
        $ref: '#/components/requestBodies/MidAuthenticationRequestBody'
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionIDResponse'
        '400':
          description: 'Bad request. Client error.'
        '403':
          description: 'Authentication failed'

  '/mid/session/{sessionID}':
    get:
      summary: Polls Mobile-ID session status
      description: |
        Polls the status of a Mobile-ID authentication session
      tags:
        - cdoc2-rp
      operationId: midSession
      parameters:
        - name: sessionID
          in: path
          required: true
          description: Unique session identifier (UUID) returned when the authentication session was created
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/SessionTokenHeader'
        - $ref: '#/components/parameters/SessionX5cHeader'
      responses:
        "200":
          $ref: '#/components/responses/MidSessionStatusResponse'
        '400':
          description: 'Bad request. Client error.'
        '403':
          description: 'Authentication failed'

  '/sid/authenticate':
    post:
      summary: Sends authentication request to SiD
      description: |
        Sends authentication request to Smart-ID
      tags:
        - cdoc2-rp
      operationId: sidAuthenticate
      parameters:
        - $ref: '#/components/parameters/SessionTokenHeader'
        - $ref: '#/components/parameters/SessionX5cHeader'
      requestBody:
        $ref: '#/components/requestBodies/SidAuthenticationRequestBody'
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionIDResponse'
        '400':
          description: 'Bad request. Client error.'
        '403':
          description: 'Authentication failed'

  '/sid/session/{sessionID}':
    get:
      summary: Sends authentication request to SiD
      description: |
        Sends authentication request to Smart-ID
      tags:
        - cdoc2-rp
      operationId: sidSession
      parameters:
        - name: sessionID
          in: path
          required: true
          description: Unique session identifier (UUID) returned when the authentication session was created
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/SessionTokenHeader'
        - $ref: '#/components/parameters/SessionX5cHeader'
      responses:
        "200":
          $ref: '#/components/responses/SessionStatusResponse'
        '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-rp
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              examples:
                Server info example:
                  value:
                    build:
                      artifact: cdoc2-rp-server-webapp
                      name: cdoc2-rp-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:
    NonceResponse:
      title: Nonce response
      type: object
      properties:
        nonce:
          type: string
          minLength: 12
          maxLength: 16
          description: 'server nonce for subsequent authentication'
      required:
        - nonce

    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: ''
                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

    SessionIDResponse:
      required:
        - sessionID
      type: object
      properties:
        sessionID:
          type: string
          format: uuid
          description: A string that can be used to request the operation result.

    SessionStatusResponse:
      type: object
      required:
        - state
      properties:
        state:
          type: string
          enum:
            - RUNNING
            - COMPLETE
          description: State of request. `RUNNING`/`COMPLETE`.
        result:
          type: object
          required:
            - endResult
          properties:
            endResult:
              type: string
              enum:
                - OK
                - USER_REFUSED
                - TIMEOUT
                - DOCUMENT_UNUSABLE
                - WRONG_VC
                - REQUIRED_INTERACTION_NOT_SUPPORTED_BY_APP
                - USER_REFUSED_CERT_CHOICE
                - USER_REFUSED_INTERACTION
                - PROTOCOL_FAILURE
                - EXPECTED_LINKED_SESSION
                - SERVER_ERROR
              description: |
                End result of the session (`OK` if session was completed successfully).

                * `OK` - session was completed successfully, there is a certificate, document number and possibly signature in return structure.
                * `USER_REFUSED` - user refused the session (except on the interaction screen).
                * `TIMEOUT` - there was a timeout, i.e. end user did not confirm or refuse the operation within given time frame.
                * `DOCUMENT_UNUSABLE` - for some reason, this RP request cannot be completed. User should either check his/her Smart-ID mobile application or turn to customer support for getting the exact reason.
                * `WRONG_VC` - in case the multiple-choice verification code was requested, the user did not choose the correct verification code.
                * `REQUIRED_INTERACTION_NOT_SUPPORTED_BY_APP` - user app version does not support any of the `interactions` interactions.
                * `USER_REFUSED_CERT_CHOICE` - user has multiple accounts and pressed Cancel on device choice screen on any device.
                * `USER_REFUSED_INTERACTION` - user has pressed cancel on the screen (except during certificate choice device selection).
                * `PROTOCOL_FAILURE` - there was a logical error in the signing protocol.
                * `EXPECTED_LINKED_SESSION` - the app received a different transaction while waiting for the linked session that follows the device-link based cert-choice session.
                * `SERVER_ERROR` - process was terminated due to server-side technical error
                * `ACCOUNT_UNUSABLE` - the account is currently unusable
            documentNumber:
              type: string
              description: Document number, can be used in further signature and authentication requests to target the same device. Mandatory if the `result.endResult` is `OK`.
            details:
              type: object
              properties:
                interaction:
                  type: string
                  description: Holds the refused interaction for the `USER_REFUSED_INTERACTION` `endResult` code.
              description: Holds extra details related to the `endResult`.
          description: Structure describing end result, may be empty or missing when `state` is `RUNNING`.
        signatureProtocol:
          type: string
          enum:
            - ACSP_V2
            - RAW_DIGEST_SIGNATURE
          description: |
            Signature protocol. Possible values:

            * `ACSP_V2` - signature protocol used for the `authentication` sessions.
            * `RAW_DIGEST_SIGNATURE` - signature protocol used for the `signature` sessions.

            See [signature protocols](./signature_protocols.html#signature_protocols) for additional details.
        signature:
          $ref: '#/components/schemas/AcspV2Signature'
        cert:
          type: object
          required:
            - value
            - certificateLevel
          properties:
            value:
              type: string
              format: byte
              contentEncoding: base64
              pattern: ^[a-zA-Z0-9+\/]+={0,2}$
              description: Certificate value, DER+Base64 encoded. The certificate itself contains info on whether the certificate is QSCD-enabled, data which is not represented by certificate level.
            certificateLevel:
              type: string
              description: |
                Level of Smart-ID certificate: `ADVANCED` or `QUALIFIED`.
          description: Structure describing the certificate related to the request. Mandatory if the `result.endResult` is `OK`.
        interactionTypeUsed:
          type: string
          enum:
            - displayTextAndPIN
            - confirmationMessage
            - confirmationMessageAndVerificationCodeChoice
          description: Name of interaction used. Mandatory if the `result.endResult` is `OK`. See section [available interactions](./interactions.html#available_interactions) for more information.
        deviceIpAddress:
          type: string
          description: IP address of the mobile device. Is present only when it has been previously requested within the session creation `requestProperties` parameter by setting `shareMdClientIpAddress` to `true`. The RP must have proper privilege to use this property.
        ignoredProperties:
          type: array
          items:
            type: string
          description: Values from `requestProperties` that were unsupported or ignored.
    AcspV2Signature:
      type: object
      additionalProperties: false
      required:
        - value
        - serverRandom
        - userChallenge
        - flowType
        - signatureAlgorithm
      properties:
        value:
          $ref: '#/components/schemas/SignatureValue'
        serverRandom:
          type: string
          format: byte
          contentEncoding: base64
          minLength: 24
          pattern: ^[a-zA-Z0-9+\/]+={0,2}$
          description: A unique value of length greater than 18 bytes generated by the RP API. It is returned by RP API in Base64 encoded form, it must be used as is, in Base64 form. There are no guarantees that the returned value length is the same in each call of the RP API.
        userChallenge:
          type: string
          contentEncoding: base64url
          minLength: 43
          maxLength: 43
          pattern: ^[a-zA-Z0-9-_]{43}$
          description: Base64URL-encoded challenge value originating from the mobile device.​ This value is derived from `userChallengeVerifier` by computing BASE64URL-ENCODE(SHA256(userChallengeVerifier)). See [Callback URLs](./callback_urls.html) page for details.
        flowType:
          $ref: '#/components/schemas/FlowType'
        signatureAlgorithm:
          $ref: '#/components/schemas/SignatureAlgorithm'
        signatureAlgorithmParameters:
          $ref: '#/components/schemas/SignatureAlgorithmParametersInResponse'
      description: Authentication Context Signature Protocol version 2 (`ACSP_V2`) makes the signature non-replayable by adding a server-side component to the signed object.
    SignatureValue:
      type: string
      format: byte
      contentEncoding: base64
      pattern: ^[a-zA-Z0-9+\/]+={0,2}$
      description: Signature value, Base64 encoded.
    FlowType:
      type: string
      enum:
        - QR
        - App2App
        - Web2App
        - Notification
      description: Similar to `deviceLinkType` in [device link flows](./device_link_flows.html#device_link_parameters) but it additionally contains `Notification` as an option. RP must make sure that the `flowType` that is returned was one of the options provided for the user.
    SignatureAlgorithmParametersInResponse:
      type: object
      properties:
        hashAlgorithm:
          $ref: '#/components/schemas/HashAlgorithm'
        maskGenAlgorithm:
          type: object
          properties:
            algorithm:
              type: string
              enum:
                - id-mgf1
              description: |
                The mask generation algorithm ID. Only a single value is supported:

                * `id-mgf1` - Mask Generator Function 1 (MGF1, OID [1.2.840.113549.1.1.8](https://oidref.com/1.2.840.113549.1.1.8)).
            parameters:
              type: object
              properties:
                hashAlgorithm:
                  $ref: '#/components/schemas/MGF1HashAlgorithm'
              description: The mask generation algorithm specific parameters.
          description: Identifies the mask generation function and its parameters.
        saltLength:
          type: integer
          description: The octet length of the salt. This parameter is fixed, and it cannot be changed or specified. This value depends on the `hashAlgorithm` parameter, and it is equal to the octet length of the hash value which is produced by that specific `hashAlgorithm`.
        trailerField:
          type: string
          enum:
            - "0xbc"
          description: The trailer field number, for compatibility with [IEEE 1363a](http://ieeexplore.ieee.org/document/1335427/). This parameter is fixed, and it cannot be changed or specified.
      description: Object with parameters for specific signature algorithm in response body. If a request is made with `rsassa-pss`, then the `signatureAlgorithmParameters` is also present in the response body. The parameters in the response body `signatureAlgorithmParameters` are needed for signature verification.
    MGF1HashAlgorithm:
      type: string
      enum:
        - SHA-256
        - SHA-384
        - SHA-512
        - SHA3-256
        - SHA3-384
        - SHA3-512
      description: Hash algorithm used for `MGF1`. The hash function for `MGF1` is defined to be the same value as the `hashAlgorithm` parameter value.
    MidHashType:
      type: string
      enum:
        - SHA256
        - SHA384
        - SHA512
      description: Hash algorithm used to compute the hash sent in the MID authentication request.

    MidLanguage:
      type: string
      enum:
        - EST
        - ENG
        - RUS
        - LIT
      description: |
        Language for user dialog in the Mobile-ID app. If the language/country combination is not supported, falls back to `ENG`.

    MidDisplayTextFormat:
      type: string
      enum:
        - GSM-7
        - UCS-2
      default: GSM-7
      description: |
        Encoding of `displayText`.

        * `GSM-7` (default) — up to 100 characters.
        * `UCS-2` — up to 50 characters.

    MidSignature:
      type: object
      required:
        - value
        - algorithm
      properties:
        value:
          type: string
          format: byte
          contentEncoding: base64
          pattern: ^[a-zA-Z0-9+\/]+={0,2}$
          description: Signature value, Base64 encoded.
        algorithm:
          type: string
          description: Signature algorithm name returned by MID (e.g. `SHA256WithECEncryption`, `SHA256WithRSAEncryption`).

    MidSessionStatusResponse:
      type: object
      required:
        - state
      properties:
        state:
          type: string
          enum:
            - RUNNING
            - COMPLETE
          description: State of the MID session.
        result:
          type: string
          enum:
            - OK
            - TIMEOUT
            - NOT_MID_CLIENT
            - USER_CANCELLED
            - SIGNATURE_HASH_MISMATCH
            - PHONE_ABSENT
            - DELIVERY_ERROR
            - SIM_ERROR
          description: |
            End result of the session. Present only when `state` is `COMPLETE`.

            * `OK` — authentication completed successfully.
            * `TIMEOUT` — user did not respond within the allowed time frame (~2 minutes).
            * `NOT_MID_CLIENT` — user has no active Mobile-ID certificates.
            * `USER_CANCELLED` — user rejected the operation on the device.
            * `SIGNATURE_HASH_MISMATCH` — mismatch between SIM and service provider configuration.
            * `PHONE_ABSENT` — SIM unavailable.
            * `DELIVERY_ERROR` — SMS delivery failure.
            * `SIM_ERROR` — invalid response from the SIM card.
        signature:
          $ref: '#/components/schemas/MidSignature'
        cert:
          type: string
          format: byte
          contentEncoding: base64
          pattern: ^[a-zA-Z0-9+\/]+={0,2}$
          description: DER+Base64 encoded authentication certificate. Present when `result` is `OK`.
        time:
          type: string
          format: date-time
          description: Server timestamp of the session completion.
        traceId:
          type: string
          description: Hex string for log correlation.

    SemanticsIdentifier:
      type: string
      description: semantics identifier of the authentication subject
    AuthCertificateLevel:
      type: string
      enum:
        - ADVANCED
        - QUALIFIED
      default: QUALIFIED
      description: Level of certificate requested.
    AuthSignatureProtocol:
      type: string
      enum:
        - ACSP_V2
      description: |
        Signature protocol. Describes the algorithm how signature is produced and the `signatureProtocolParameters` object. Currently, the only allowed value is:

        * `ACSP_V2` - Data structure for authentication context to be signed. For more details, see section [`ACSP_V2` protocol](./signature_protocols.html#acsp_v2_signature_protocol).
    AuthSignatureProtocolParameters:
      type: object
      required:
        - rpChallenge
        - signatureAlgorithm
      properties:
        rpChallenge:
          type: string
          format: byte
          contentEncoding: base64
          minLength: 32
          maxLength: 64
          pattern: ^[a-zA-Z0-9+\/]+={0,2}$
          description: |
            A random value which is randomly generated by the RP backend with size in the range of 32 bytes - 64 bytes and applying Base64 encoding (according to [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648)). It must be freshly generated for each `authentication`.

            The recommended way of generating the `rpChallenge` is to use the [Java `SecureRandom` class](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/security/SecureRandom.html) or equivalent method in other programming languages.

            The `rpChallenge` must be kept in the current user's session on the RP backend for the duration of the `authentication` session, and later must be used to reconstruct and validate the signed authentication data structure.
        signatureAlgorithm:
          $ref: '#/components/schemas/SignatureAlgorithm'
        signatureAlgorithmParameters:
          $ref: '#/components/schemas/SignatureAlgorithmParametersInRequest'
      description: An object describing the parameters of the signature algorithm.
    SignatureAlgorithm:
      type: string
      enum:
        - rsassa-pss
        - sha256WithRSAEncryption
        - sha384WithRSAEncryption
        - sha512WithRSAEncryption
      description: |
        Digital signature algorithm name. This is a reference name to algorithm defined in Public-Key cryptography standards. RSASSA-PSS is the default and recommended algorithm. RSASSA-PKCS1-v1_5–based algorithms are deprecated and should only be used if RSASSA-PSS is not available.

        * `rsassa-pss` - Rivest, Shamir, Adleman (RSA) Signature Scheme with Appendix - Probabilistic Signature Scheme (RSASSA-PSS) [RFC8017, Appendix A.2.3](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.2.3), OID [1.2.840.113549.1.1.10](https://oidref.com/1.2.840.113549.1.1.10). If a request is made with `rsassa-pss`, then the `signatureAlgorithmParameters` must be present in the request body.
        * `sha256WithRSAEncryption` - *DEPRECATED.* Secure Hash Algorithm 256 (SHA-256) with Rivest, Shamir and Adleman (RSA) encryption [RFC8017, Appendix A.2.4](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.2.4), OID [1.2.840.113549.1.1.11](https://oidref.com/1.2.840.113549.1.1.11). This algorithm *does not require* `signatureAlgorithmParameters`.
        * `sha384WithRSAEncryption` - *DEPRECATED.* Secure Hash Algorithm 384 (SHA-384) with Rivest, Shamir and Adleman (RSA) Encryption [RFC8017, Appendix A.2.4](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.2.4), OID [1.2.840.113549.1.1.12](https://oidref.com/1.2.840.113549.1.1.12). This algorithm *does not require* `signatureAlgorithmParameters`.
        * `sha512WithRSAEncryption` - *DEPRECATED.* Secure Hash Algorithm 512 (SHA-512) with Rivest, Shamir and Adleman (RSA) encryption [RFC8017, Appendix A.2.4](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.2.4), OID [1.2.840.113549.1.1.13](https://oidref.com/1.2.840.113549.1.1.13). This algorithm *does not require* `signatureAlgorithmParameters`.
    SignatureAlgorithmParametersInRequest:
      type: object
      required:
        - hashAlgorithm
      properties:
        hashAlgorithm:
          $ref: '#/components/schemas/HashAlgorithm'
      description: Object with parameters for specific signature algorithm in request bodies. If a request is made with `rsassa-pss`, then the `signatureAlgorithmParameters` and `signatureAlgorithmParameters.hashAlgorithm` must be present in the request body.
    HashAlgorithm:
      type: string
      enum:
        - SHA-256
        - SHA-384
        - SHA-512
        - SHA3-256
        - SHA3-384
        - SHA3-512
      description: |
        Hash algorithm that is either:

        * used to compute the digest from the `ACSP_V2` data structure for authentication requests,
        * used by the RP to generate the digest from the data-to-be-signed for signature requests.

        Also used internally by the `rsassa-pss` signature algorithm the as the mask generation algorithm (`MGF1`) hash algorithm.
    InteractionsNotificationBased:
      type: string
      format: byte
      contentEncoding: base64
      pattern: ^[a-zA-Z0-9+\/]+={0,2}$
      description: "Base64 encoded representation of a JSON object that lists the supported interaction types.\n\nFollowing interaction types are allowed:\n\n1. `displayTextAndPIN` with `displayText60`\n2. `confirmationMessage` with `displayText200`\n3. `confirmationMessageAndVerificationCodeChoice` with `displayText200`\n\n**Warning!** Serializing a JSON object may produce different byte representations depending on the JSON library or serialization settings. \nCare must be taken to use the exact same Base64-encoded `interactions` object in session initiation and all subsequent calculations.\n\nFor more details, see section [interactions](./interactions.html#interactions).\n"
    RequestProperties:
      type: object
      properties:
        shareMdClientIpAddress:
          type: boolean
          default: false
          description: |
            Mobile device IP address is shared to authorized RP, who are able to use the data in their transaction monitoring mechanisms to detect unauthorized or fraudulent transactions by comparing this shared IP address with the IP address, that `person` represents to the RP during interaction with RP services.

            The IP address is saved to the RP session when `person` reacts to the `RpRequest` with one of its mobile devices. Saved IP address is returned to the RP in the session status response only if all of the following are true:

            * The RP has privileges to request mobile device IP address (default configuration does not allow the IP sharing).
            * The RP requests the mobile device IP address via `requestProperties` of RP request. The optional property option `shareMdClientIpAddress` must be set to `true`. If property is not defined, or is set to `false` in the RP request, IP address won't be shared in session.
            * The RP session is complete.
            * The mobile device IP address was successfully saved to the RP session.
      description: |
        Additional properties to some of the requests can be included for requesting some desired behavior using the request parameter `requestProperties`. Currently, only one property is supported:

        * `shareMdClientIpAddress` - Whether the RP API server should share user mobile device IP address with the RP. By default it is set to `false`. The RP must have proper privilege to use this property.

        Any unsupported property is ignored and is listed in the `ignoredProperties` parameter of the session status response.
    Capabilities:
      type: array
      items:
        type: string
      description: Used only when agreed with Smart-ID provider. When omitted request capabilities are derived from `certificateLevel` parameter.
    VerificationCodeType:
      type: string
      enum:
        - numeric4
      description: The Verification Code (VC) type to use.

  parameters:
    SessionTokenHeader:
      name: x-cdoc2-session-token
      in: header
      required: true
      schema:
        type: string
      description: |
        SDJWT [Session token WIP](). Signed by cdoc2-auth-server using key identified by 
        'kid' in JWT header. Contains a MID/SID signature as part of the payload. 'aud' claim
        contains selectively-disclosed array element identifying a session nonce that is 
        checked by the server x-cdoc2-session-token is presented to.

    SessionX5cHeader:
      name: x-cdoc2-session-x5c
      in: header
      required: true
      schema:
        type: string
      description: |
        Base64Url-encoded DER certificate that was used to generate the MID/SID signature in x-cdoc2-session-token payload. 
        Certificate holder's identity is specified in Subject "serialnumber" field. Example certificate subject: 
        'serialNumber = PNOEE-30303039914, GN = OK, SN = TESTNUMBER, CN = "TESTNUMBER,OK", C = EE'
        Certificate full structure is defined in 
        [Certificate and OCSP Profile for Smart-ID](https://www.skidsolutions.eu/wp-content/uploads/2024/10/SK-CPR-SMART-ID-EN-v4_7-20241127.pdf)
      

  requestBodies:
    MidAuthenticationRequestBody:
      required: true
      content:
        application/json:
          schema:
            required:
              - phoneNumber
              - nationalIdentityNumber
              - hash
              - hashType
              - language
              - displayText
              - displayTextFormat
            type: object
            properties:
              phoneNumber:
                type: string
                description: Phone number of the signer with country code prefix, e.g. `+3726234566`.
                example: '+3726234566'
              nationalIdentityNumber:
                type: string
                description: National identity number of the signer (without country prefix), e.g. `38412319871`.
                example: '38412319871'
              hash:
                type: string
                format: byte
                contentEncoding: base64
                pattern: ^[a-zA-Z0-9+\/]+={0,2}$
                description: Base64-encoded hash value that is signed by the user's Mobile-ID SIM card. Must be freshly generated for each request using a cryptographically secure random source.
              hashType:
                $ref: '#/components/schemas/MidHashType'
              language:
                $ref: '#/components/schemas/MidLanguage'
              displayText:
                type: string
                description: Text displayed to the user on the Mobile-ID app. Max 100 bytes in `GSM-7` encoding or 50 characters in `UCS-2` encoding.
              displayTextFormat:
                $ref: '#/components/schemas/MidDisplayTextFormat'
          examples:
            Mobile-ID authentication request sample:
              $ref: '#/components/examples/MidAuthenticationRequestBodyExample'

    SidAuthenticationRequestBody:
      required: true
      content:
        application/json:
          schema:
            required:
              - semanticsIdentifier
              - signatureProtocol
              - signatureProtocolParameters
              - interactions
              - vcType
            type: object
            properties:
              semanticsIdentifier:
                $ref: '#/components/schemas/SemanticsIdentifier'
              certificateLevel:
                $ref: '#/components/schemas/AuthCertificateLevel'
              signatureProtocol:
                $ref: '#/components/schemas/AuthSignatureProtocol'
              signatureProtocolParameters:
                $ref: '#/components/schemas/AuthSignatureProtocolParameters'
              interactions:
                $ref: '#/components/schemas/InteractionsNotificationBased'
              requestProperties:
                $ref: '#/components/schemas/RequestProperties'
              capabilities:
                $ref: '#/components/schemas/Capabilities'
              vcType:
                $ref: '#/components/schemas/VerificationCodeType'
          examples:
            Smart-ID authentication request sample:
              $ref: '#/components/examples/SidAuthenticationRequestBodyExample'

  responses:
    MidSessionStatusResponse:
      description: OK
      headers:
        x-rp-signed-hash:
          schema:
            type: string
          description: 'signed hash'
          example: 'B+C9XVjIAZnCHH9vfBSv...'
        x-rp-name:
          schema:
            type: string
          description: 'rp name'
          example: 'cdoc2-RP.example.ee'
        Signature-Input:
          schema:
            type: string
          description: 'HTTP Signature-Input header (https://datatracker.ietf.org/doc/rfc9421/)'
          example: 'sig1=("x-rp-signed-hash" "x-rp-name");created=1715269200;keyid="f4e8b6b4-6a8e-4f77-987c-0957d1dc7f73"'
        Signature:
          schema:
            type: string
          description: 'HTTP Signature header (https://datatracker.ietf.org/doc/rfc9421/)'
          example: 'sig1=:<Base64-encoded-signature>:'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MidSessionStatusResponse'
          examples:
            MID OK Example:
              $ref: '#/components/examples/MidSessionStatusResponseExample'

    SessionStatusResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SessionStatusResponse'
          examples:
            ACSP_V2 Example:
              $ref: '#/components/examples/AcspV2ResponseExample'

  examples:
    MidAuthenticationRequestBodyExample:
      value:
        phoneNumber: '+3726234566'
        nationalIdentityNumber: '38412319871'
        hash: 0nbgC2fVdLVQFZJdBbmG8B+kXnZtX1FSTM59UVDQ4Gc=
        hashType: SHA256
        language: ENG
        displayText: Decrypting container file "test.txt"
        displayTextFormat: GSM-7

    MidSessionStatusResponseExample:
      value:
        state: COMPLETE
        result: OK
        signature:
          value: B+C9XVjIAZnCHH9vfBSvXgFN2oT4RuCvYLkE==
          algorithm: SHA256WithECEncryption
        cert: MIIFijCCBHKgAwIBAgIJAL3NmQGsd536MA0GCSqGSIb3DQEBCwUAMC8xCzAJ
        time: '2026-05-12T10:52:20Z'
        traceId: d8de38e7bb5d8f8a

    SidAuthenticationRequestBodyExample:
      value:
        certificateLevel: QUALIFIED
        signatureProtocol: ACSP_V2
        signatureProtocolParameters:
          rpChallenge: S480uRoCX4pAb1tWqAy8WGl/AWE1RnqaP2y5iamCDhlCyQrMTVa5d8Dh34sZ+UePHXRNKTwz7QTvsIL1ls05AQ==
          signatureAlgorithm: rsassa-pss
          signatureAlgorithmParameters:
            hashAlgorithm: SHA-512
        interactions: W3sidHlwZSI6ImNvbmZpcm1hdGlvbk1lc3NhZ2UiLCJkaXNwbGF5VGV4dDIwMCI6IkRlY3J5cHRpbmcgY29udGFpbmVyIGZpbGUgXCJ0ZXN0LnR4dFwiIn0seyJ0eXBlIjoiZGlzcGxheVRleHRBbmRQSU4iLCJkaXNwbGF5VGV4dDYwIjoiRGVjcnlwdGluZyBjb250YWluZXIgZmlsZSBcInRlc3QudHh0XCIifV0=
        vcType: numeric4

    AcspV2ResponseExample:
      value:
        state: COMPLETE
        result:
          endResult: OK
          documentNumber: PNOEE-30001010004-BVFM-Q
        signatureProtocol: ACSP_V2
        signature:
          value: Vak2Q0NiFnh6+lW+YaJuB8yMYM7k3I5QfsUxS3Y1Ddm3qy6HvebLl0/t17dq289/+4mGx45qnHVNj1CzqF88lYFpwAQXFc5XiHtYbvnENgjwLSfrQ9mrSt0phemAK29GzAexilPPy5+PdeCdO+TEuMIhi/qkKhL+lk5d1flmrWZQ4B0H7kXTqRjJvCAUc8bsdM7SLV5jZuEIhOqTCsyDY3FZmyJi4ms8SsOmYCy/Do20CIiQbv75eunKfTKciqVnOA+WYN5OXLJVqhgaHJ+hYiYA+QXOvIIYKVIUdB1rDRnKwwvZk1lZ3oKW1r7XGkovbmwRz+NpmHTyMUubXXQHYah3T4h7vf0C14MBpupWRB47s6rsdPZzH2No7AoDGjMGAMEWg5rdB45fYXbjRV2T69e4c47VpubG1DXTsoXowe/yzXdIjUYfZDwozzW6+IXTdAKL4LP6wmCU+PxP/GfYQ1k1w3fXjh4XeO9QmipRDEle2l0z6nYJaGuIYCb7pDh6ZoJllyKSmhqWG0PMLod34Lo1MMP4WGvLe86/fiTFPbh/VR981MIjz5xIRaSxFZQmNzI5IvzORskgsHGALb7Nb51q3jPKE2D1UOrQN6N6DMbGFMFR/7vRgkvUbeC0jAWevVrssEK77d5OmgXqk7sevYDwP1WnmBwr2ov/Tt+AM58BTgdHsnWRw6hL1mS9+DzCaCuDb/+vspiZnVjP9S9ckmCLP8yrwzL8Myj5lS62Rta727GulSUet21euQl0E2CuDpSoiKuO3NkYWqskfCowb0GiiX0oZe98mFiBFo1Za5Tb207fPOQyGAwY29k0/XaYxwMPsU7/hwI5Ba8iek1A09Et3HB0q0hXeKyWl425ZrMdVoOMnVyquBNo/FhAOvoSGUyiIUSDdpSwgpiJAH5cVX3W6lOy93mNtPBMk0qxtItYD3b9N7Lut6SCLhL/IGoNmrouOUX3xM8KD8qgnXmUXF0996YK9WxFfZ8HScFVno8kRZdDY4QinqcwZy+FNXBG
          serverRandom: +wVP2U/SMKVkVrggDjNTXFV/
          userChallenge: TLSjYRH2oYw8tW2bq0it0IUb7WIFkCLgF8NTc7-4Zq4
          flowType: Notification
          signatureAlgorithm: rsassa-pss
          signatureAlgorithmParameters:
            hashAlgorithm: SHA-512
            maskGenAlgorithm:
              algorithm: id-mgf1
              parameters:
                hashAlgorithm: SHA-512
            saltLength: 64
            trailerField: "0xbc"
        cert:
          value: MIIFijCCBHKgAwIBAgIJAL3NmQGsd536MA0GCSqGSIb3DQEBCwUAMC8xCzAJBgNVBAYTAkVFMQ4wDAYDVQQKEwVDeWJlcjEQMA4GA1UEAxMHVEMgcm9vdDAeFw0yNTA2MTIxNDM4NDVaFw0yNjA2MTIxNDM4NDVaMIGGMQswCQYDVQQGEwJFRTENMAsGA1UEBAwES2FydTENMAsGA1UEKgwETWF0aTEaMBgGA1UEBRMRUE5PRUUtMzAwMDEwMTAwMDQxJDAiBgNVBAMMG0thcnUsTWF0aSxQTk9FRS0zMDAwMTAxMDAwNDEXMBUGA1UECwwOQVVUSEVOVElDQVRJT04wggMhMA0GCSqGSIb3DQEBAQUAA4IDDgAwggMJAoIDAHPLxyGpzYxygWyvfzju5axnHv2xyiHzSW7adv12BmrWz+W/Hjah1V3OJo3mqG6rG2LI90wNXEbQD2QS/wRI4ksVcdsnmoF5489etoW228YtcGJdIfoUDMW9bz1u4pKdQYHJBnyHo2MmL6q4r2Uyj5comPVRgaL1r16CO+n/Hi9zzomRSQ7bE5zlLaWdRjgeW33hyfy2ZQJAo3MuQ1kxqNEUGLtxhDiEN3kH7M45wikZE1EDV3yNEhrW/xAxmuLCDzY4Y+FfJ+d3H6n+3rhAgk72NfbEtR8AHjV0yj/1KdQt60muSGQ+mDSUcPaUzc9X1QrFvg01l1GcFTkM409AqskZaFFHVUs6/nHItnJO0edQS2/7G0LPPy794QwOUXamlJUZjpmNN39d5SR3WsdonzI8ZEV+PsdAqaHFbSso0fH/59XU0Vlmcy2OvXnff0IYtTWaz1+UT4KrVjPXfbUDuKiaAGKCAaNluH9NxcmVy//qoVui8zGm/swnCJxAMQhdV8Le4gEDWeJiNoUHnypdSgPevccLSxTMXSAnm/MAjXF2XZxefJeaOiVXOGEVr7c+NlMb5wtPlThHcCt9vQoKl+UFIRrSgT7J3u96SU7lFoB3CLwIVYLpmrI498iTpNsqydPGejhWHOpPsK9CSHxrtIeKHExpD2BpUxwJr1/FwwwgwRA0n0uYWk+eo5tJfxFg8FjCTxDbLuVS/DM28DmOyqydcIwkckPXBJeE/ZLHhPEbeLo5z+wCIL/Ao56UFxGrpT+slL80E2EV5ZIXLRH9q0/OzDXEJe/5nOi8pAzE7s4/pLoIlS2gJl8qIFqyrtxkTgRnrbqKftZ+ljrHgEJvUoZ64rSe+Ze4BUpjmPsSFefc5sQNq7QB6vJ860rARStDYwee7c8bZM4pnYYjXbzUATcR74445SYC92q8R6vTRZqGohP9IsrbQrVLMd7k5BEk3QyZAxhBYL1oJJCuB1fQp9orONLg5y9mmBwK/Udb0x4Rzb+sSdnrSDhegdhQbutQZwIDAQABo1IwUDAfBgNVHSMEGDAWgBR34yPLMQW8zhFBhUVMMmjuqyKPxzAdBgNVHQ4EFgQUG8uAz/1qNL+ofmnbWF3IurCBAiMwDgYDVR0PAQH/BAQDAgSwMA0GCSqGSIb3DQEBCwUAA4IBAQA/+yzSFT2Udyol0jspwqidpe0A9YFxJzU8C5i/zyDVQOV+krMS78vBNW83r14YpRxbIHXIjh3HO/oeRseEvVh5yuSYz5lexIjWATKUGOWVZac+gqrTJKuBryqWy7pjAP36knGAaGC17u/Ool/XCUb+K5yZKwsGpzOn9GOx02+0QPVhYy4iC+sJlyUWvLbwNLmf8Nkm00gMPKVUDoDHwiX35wq3ZnuuTOTMMRxx3fszdRKGklt3KytgKGnii+8+Tz3Hh1G6IuRqiMkOpI8dUvi3ywYY72HNjd6ge4Qs2Y2zBxU8XLLBwMYJgwTFoe4JFhsjr32teZZTihlk9Me44dBI
          certificateLevel: QUALIFIED
        interactionTypeUsed: displayTextAndPIN

  securitySchemes:
    bearerAuth: # long-term token
      type: http
      scheme: bearer
    basicAuth: # temporary solution
      type: http
      scheme: basic
    SdJwtAuth:
      type: http
      scheme: bearer
      bearerFormat: SD-JWT
      description: |
        CDOC2 SD-JWT

        https://open-eid.github.io/CDOC2/2.0-Draft/03_system_architecture/ch06_ID_authentication_protocol/#creating-sd-jwt-structure-authentication-data-and-authentication-signature

tags:
  - name: cdoc2-rp