Changelog

RP API version 3.2 changes compared to version 3.1

API changes

  • RP API v3 now supports both HTTP/1.1 and HTTP/2 protocols.

  • Custom HTTP response status codes (471 and 472) are no longer used. These have been replaced with 404 (see OpenAPI specification for overview of possible HTTP error codes for each request). The error details are provided according to RFC9457 format.

Documentation changes

RP API version 3.1 changes compared to version 2

This changelog outlines the key differences between Relying Party (RP) API version 3.1 and version 2. Note that version 3.0 was not widely publicly released.

New features

  • Added device link based interaction flows (QR code, Web2App, App2App) for authentication, signing, and certificate-choice.

  • Added distinct API endpoints for device link and notification based flows.

    • Example: /v3/authentication/device-link/…​ vs. /v3/authentication/notification/…​

  • App2App and Web2App device link flows include a mandatory initialCallbackUrl parameter. It is used to construct the final callback URL to which the end-user is redirected after a successful PIN entry.

  • Added new signature protocols:

    • ACSP_V2 (Authentication Context Signing Protocol)

    • RAW_DIGEST_SIGNATURE (signing pre-computed digests)

  • Added capability to link a device link based certificate-choice request to a subsequent notification based signature request via /v3/signature/notification/linked/{document-number}.

  • Added an endpoint /v3/signature/certificate/{document-number} to request signing certificates when document number is know. This means that certificate-choice should only be used now before signature sessions in cases where document number is not know (e.g., no prior Smart-ID authentication).

Security enhancements

  • To prevent replay attacks, the mandatory rpChallenge parameter (an RP-generated random value) has been introduced for all initial v3 requests, effectively replacing the nonce parameter used in v2.

  • The RSASSA-PKCS#1 v1.5 signature padding scheme has been removed and is replaced by RSASSA-PSS, which is now the only supported option for RSA signatures.

    • This change includes support for SHA-3 hash algorithms (SHA3-256, SHA3-384, SHA3-512) with RSASSA-PSS.

  • Revised Verification Code (VC) generation for notification flows:

    • Authentication flows: VC is derived from rpChallenge.

    • Signing flows: VC is randomly generated by the Smart-ID RP API server.

  • Introduced a possibility for new verification code formats in the future. For now, the existing format (four numbers) will still be the only option.

  • App2App and Web2App device link flows now require callback verification process as part of the response verification process.

API endpoint and parameter changes

  • The certificatechoice (v2) functionality is now certificate-choice (v3).

    • It has been moved to /v3/signature/certificate-choice/…​.

    • It now also supports device link based flows.

  • The allowedInteractionsOrder parameter has been renamed to interactions, and its value (a JSON array of objects) must now be Base64 encoded.

  • The standalone interaction type verificationCodeChoice has been removed. Use confirmationMessageAndVerificationCodeChoice instead for flows that require a verification code choice.

  • The RP API server now provides the device link base URL to RPs.

  • The session status response (GET /session/{sessionID}) now includes userChallenge and flowType.

  • Added interactionTypeUsed to v3 responses.

  • Added new session result.endResult status codes:

    • USER_REFUSED_INTERACTION

    • PROTOCOL_FAILURE

    • SERVER_ERROR

  • USER_REFUSED_INTERACTION replaced previous result.endResult status codes (the used interaction type is now provided separately):

    • USER_REFUSED_DISPLAYTEXTANDPIN

    • USER_REFUSED_VC_CHOICE

    • USER_REFUSED_CONFIRMATIONMESSAGE

    • USER_REFUSED_CONFIRMATIONMESSAGE_WITH_VC_CHOICE

  • Error responses now use RFC9457 format.

RP API version 2 changes compared to version 1

  • Uses v2 instead of v1 in URL, {rp-api-baseurl}/v2/ instead of {rp-api-baseurl}/v1/.

  • Introduced allowedInteractionsOrder parameter to authentication and signing requests which replaces displayText and requestProperties.vcChoice parameters.

  • Added interactionTypeUsed parameter to the session status response message.

  • Added new session result.endResult status codes:

    • REQUIRED_INTERACTION_NOT_SUPPORTED_BY_APP

    • USER_REFUSED_DISPLAYTEXTANDPIN

    • USER_REFUSED_VC_CHOICE

    • USER_REFUSED_CONFIRMATIONMESSAGE

    • USER_REFUSED_CONFIRMATIONMESSAGE_WITH_VC_CHOICE

    • USER_REFUSED_CERT_CHOICE

  • Added requestProperties parameter for /v2/certificatechoice endpoint.

  • New option shareMdClientIpAddress for parameter requestProperties

  • Removed previously deprecated object reference pno/:country/:national-identity-number. Use etsi/:id-etsi-qcs-SemanticsId-Natural instead.

  • RPs must ignore any unknown names (fields) in the JSON response object.