Overview of API endpoints

The Relying Party API provides five different types of endpoints. The first four are POST requests that return a sessionID and the fifth is a GET request used to query for the result based on the sessionID.

  • The POST v3/authentication/* session endpoints are used to log a user onto a system or otherwise verify the identity of a user;

  • the POST v3/signature/* session endpoints are used to create digital signatures;

  • the POST v3/signature/certificate/{document-number} endpoint is used to obtain the signing certificate of the requested document number;

  • the POST v3/signature/certificate-choice/* session endpoints ([1], [2] and [3]) are used when the document number is not known immediately prior to the signature session and the user’s signing certificate is required to create the object that will be signed;

  • finally, the GET v3/session/{sessionID} status endpoint provides the result of the above sessions.

The implementation details are described on the OpenAPI specification page.

There are two types of flows that can be used in v3/authentication/*, v3/signature/* and v3/signature/certificate-choice/* sessions - the device link based flow and the notification based flow.

NOTE

In order to improve security and prevent phishing attacks, it is recommended to only use device link based flows or only allow notification based flows on devices and browsers that have successfully completed a device link based flow beforehand. It is up to the RP to decide how to securely identify such devices/browsers and tie them to the user’s Smart-ID personal number by utilizing browser cookies, local app storage or other means.

See additional security measures page for more details.

There are different ways to reference users - via their issued identifier, a document number linking a specific account or even not at all (in case of anonymous device link based flows). The different object references are described on the OpenAPI specification page.

IMPORTANT

Once a user has been identified within an RP session, then in subsequent signing and certificate-choice requests the document-number reference should be used.

Choosing which endpoints to use

The following diagram shows main authentication flows and which endpoints to use:

flow

The following diagram shows main signature flows and which endpoints to use:

flow

Authentication

In order to authenticate a user, RPs must create a random challenge and use RP API to get user signature on it.

Device link based authentication

Using the device link based flow is the most secure option and should be preferred.

RP may call the anonymous device link based authentication session endpoint and display a dynamic QR code that the user must scan with the Smart-ID app or show a same-device (Web2App, App2App) link the user can interact with.

  • BASE/v3/authentication/device-link/anonymous

Instead of using the anonymous authentication session endpoint, the RP may request the user to enter their user identifier and utilize the non-anonymous authentication session endpoint. This may be beneficial when the RP utilizes custom usernames and has the users' identifiers stored internally. The RP may simply always ask the user for the identifier as well.

  • BASE/v3/authentication/device-link/etsi/{id-etsi-qcs-SemanticsId-Natural}

If there is a need to re-authenticate the user, the following endpoint should be used with the previously obtained document-number instead:

  • BASE/v3/authentication/device-link/document/{document-number}

Notification based authentication

Notification based authentication session endpoint can also be used for the same purpose.

Using a notification based authentication session endpoint triggers a push notification to all the user’s devices instead of the user scanning the QR code or clicking the same-device link.

  • BASE/v3/authentication/notification/etsi/{id-etsi-qcs-SemanticsId-Natural}

If there is a need to re-authenticate the user, the following endpoint can be used with the previously obtained document-number instead:

  • BASE/v3/authentication/notification/document/{document-number}

Signing

In order to obtain an electronic signature of a document (ASiC-E with XAdES/CAdES or PDF with PAdES), RPs must create the document structure themselves, calculate the hash, and use RP API to get user signature on it.

Signing can be done in two ways—​with or without prior Smart-ID authentication. Where applicable and reasonable, Signing with prior authentication should be preferred. However, there are valid use cases for Signing without prior authentication.

Signing with prior authentication

If a user has already logged onto the RP app or website using Smart-ID authentication, the RP can call the certificate session endpoint to obtain the user’s signing certificate. As the document number is attained from the preceding authentication call, no user interaction is required for obtaining the certificate and the RP API can immediately provide it.

  • BASE/v3/signature/certificate/{document-number}

Device link based signing with prior authentication

The RP can then call the device link based signature session endpoint to sign using the same Smart-ID account that was used for authentication.

  • BASE/v3/signature/device-link/document/{document-number}

Notification based signing with prior authentication

The notification based signature session endpoint can also be used for the same purpose.

  • BASE/v3/signature/notification/document/{document-number}

Signing without prior authentication

If no prior Smart-ID authentication has taken place, signing request may be done directly. For this, a signing certificate is still most likely required to be obtained first (this is true for all use cases known in practice, e.g. ASiC-E with XAdES/CAdES or PDF with PAdES).

For obtaining the certificate and getting the user’s signature, the recommended way is to use the linked signing flow which is a new concept introduced in RP API v3. Linked signing flow consists of an anonymous device link based certificate-choice request followed by a notification based signing request.

Linked signing (without prior authentication)

In case no prior Smart-ID authentication has taken place, and certificate is required, the anonymous device link based certificate-choice session endpoint should be used.

  • BASE/v3/signature/certificate-choice/device-link/anonymous

Immediately after receiving the response with the certificate, RP must call the notification based linked signature session endpoint and provide the mandatory linkedSessionID parameter (session ID of the previous certificate-choice session) to connect the signature and certificate-choice sessions.

  • BASE/v3/signature/notification/linked/{document-number}

The combination of device link based certificate-choice and notification based linked signature session endpoints provides the optimal user experience where Smart-ID app is launched only once and a verification code (VC) is not shown. If the certificate-choice session was completed using a same-device device link, then as the final step of the signing process, the Smart-ID app will launch the callbackUrl (which was provided in the device link based certificate-choice request that initiated the linked signing flow). The callbackUrl the user will end up will also have additional parameters as explained in Callback URLs page.

NOTE

In the flow described above, it is recommended to stop showing the QR code, Web2App or App2App link in the RP UI after the certificate is obtained.

Notification based signing without prior authentication

Notification based certificate-choice session endpoint can also be used for the same purpose but is not recommended.

In this case, first use notification based certificate-choice session endpoint:

  • BASE/v3/signature/certificate-choice/notification/etsi/{id-etsi-qcs-SemanticsId-Natural}

Immediately after receiving the response with the certificate, RP must display the VC and call notification based signature session endpoint.

  • BASE/v3/signature/notification/document/{document-number}

IMPORTANT

Notification based certificate-choice cannot be connected to notification based linked signature session endpoint with linkedSessionID. If notification based certificate-choice is used, verification code (VC) must still be shown to the user, and in same-device use cases, there might be usability issues with VC being shown too fast or not being shown at all (this is especially problematic for interactions involving confirmationMessageAndVerificationCodeChoice).

Device link based signing without prior authentication and without certificate

If the certificate is not required, the device link based signature session endpoint should be called instead. Essentially this means that it is acceptable that the end user gives the signature using any of the Smart-ID devices in their possession.

  • BASE/v3/signature/device-link/etsi/{id-etsi-qcs-SemanticsId-Natural}

NOTE

There is no anonymous device link based signature session endpoint, since in all practical signing use cases the user’s identity is known beforehand.