Overview

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-choice/* session endpoints 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;

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

  • 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 Smart-ID document-number by utilizing browser cookies, local app storage or other means.

For more details on additional security measures RPs can deploy, see the additional security measures page.

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 device link based flows). The different object references are described on the OpenAPI specification page.

IMPORTANT

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

The main use cases and which sessions and flows to use are described below. Utilizing the RP API as described below provides the best user experience and security.

In the URL examples below and other pages BASE refers to the RP API base address https://rp-api.smart-id.com

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

Cross-device use cases

Use case: The RP session is on a separate device from the mobile phone where the Smart-ID app is installed.

For example, the user is using a PC browser to access an RP website or a tablet to access an RP application.

Same-device use cases

Use case: The RP frontend (whether an RP app or website accessed by a mobile browser) resides on the same mobile device as the Smart-ID app.

The end user is using a mobile app or RP detects that the user is on a mobile browser so it can be assumed that the user intends to use the Smart-ID app on a same device.

Strongly prefer the BASE/v3/*/device-link/anonymous endpoints for same-device use cases unless the user’s document-number has already been established for the current session. These endpoints provide a superior user experience as no user identifier entry is required while the device-links with callbacks provide the best security protections.

However, a fallback option should also be provided to switch to the cross-device use cases.

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

Signing with prior Smart-ID 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 the certificate-choice session and the RP API can immediately provide the certificate.

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

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 Smart-ID 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 Smart-ID authentication

If possible, the Smart-ID authentication should be performed before signing and (and after that is completed, instructions in Signing with prior Smart-ID authentication should be followed).

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, after the flow is completed, the Smart-ID app will launch the callbackUrl given in the device link based certificate-choice.

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.

If the certificate is not required, or is already known, the device link based signature session endpoint should be called instead.

  • 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.

Notification based signing without prior Smart-ID authentication

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

  • 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).