Session types

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

Their implementation details are described in their respective subpages.

There are two types of flows that can be used for authentication and signature sessions - the notification based flow and the dynamic link based flow.

The certificatechoice session can only be used with notification based flow.

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 dynamic link based flows). The different object references are described on a dedicated page.

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://https://rp-api.smart-id.com

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

Authentication

Using the dynamic link based flow with QR codes is the most secure:

RP calls the anonymous dynamic link based authentication session endpoint and displays a QR code that the user must scan with the Smart-ID app.

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

Instead of using the anonymous authentication session endpoint, the RP can 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.

  • BASE/v3/authentication/dynamic-link/etsi/:id-etsi-qcs-SemanticsId-Natural

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

In order to improve security and prevent phishing attacks, it is recommended to only allow notification based flows on devices and browsers that have successfully completed a dynamic link based flow beforehand. It is up to RP to decide how to identify such devices/browsers (e.g. by setting up a unique device identifier and storing it in the browser’s cookies).

Using a notification based authentication session endpoint triggers a push notification to all the user’s devices instead of the user having to scan QR codes.

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

Signing with prior authentication

Without certificate query

If a user has already logged onto the RP app or website using Smart-ID authentication, the RP can call the notification based signature session endpoint to sign using the same Smart-ID account that was used for authentication.

In order to improve security and prevent phishing attacks, it is recommended to only allow notification based flows on devices and browsers that have successfully completed a dynamic link based flow beforehand. It is up to RP to decide how to identify such devices/browsers (e.g. by setting up a unique device identifier and storing it in the device).

The document number is attained from the preceding authentication call.

  • BASE/v3/signature/notification/document/:documentnumber

With certificate query

In many cases, the user’s signing certificate is required before the signature session can be initiated. Calling the notification based certificatechoice session endpoint allows obtaining it. As the document number is already known, no user interaction is required for the certificatechoice session and the RP API can immediately provide the certificate.

  • BASE/v3/certificatechoice/notification/document/:documentnumber

Immediately after receiving the response with the certificate, RP should call the notification based signature session endpoint. The Smart-ID app will wait for the signature session and return only after it has been completed.

  • BASE/v3/signature/notification/document/:documentnumber

Signing without prior authentication

Without certificate query

In case no prior authentication has taken place, the dynamic link based signature session endpoint should be called.

  • BASE/v3/signature/dynamic-link/etsi/:id-etsi-qcs-SemanticsId-Natural

With certificate query

Often though the certificate is required prior to the signing request. For this, RP should first call the notification based certificatechoice session endpoint.

  • BASE/v3/certificatechoice/notification/etsi/:id-etsi-qcs-SemanticsId-Natural

Immediately after receiving the response with the certificate, RP should call the notification based signature session endpoint.

  • BASE/v3/signature/notification/document/:documentnumber

Single-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 client 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 the same device.

However, a fallback option should also be provided to switch to the separate device use case.

Authentication

Use the anonymous dynamic link based authentication session endpoint for App2App and Web2App flows.

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

Alternatively, the non-anonymous flow can be used to too.

  • BASE/v3/authentication/dynamic-link/etsi/:id-etsi-qcs-SemanticsId-Natural

As a fallback (in case the Smart-ID app is on a separate account), RP should provide an option to use QR codes instead of the App2App or Web2App link. There is no need to query the RP API again for this.

Signing with prior authentication

Without certificate query

Call the dynamic link based signature session endpoint and provide the document number from the authentication session to ensure the same account is being used.

  • BASE/v3/signature/dynamic-link/document/:documentnumber

With certificate query

As the document number is already known, no user interaction is required for the certificatechoice session and the RP API can immediately provide the certificate.

In order to improve security and prevent phishing attacks, it is recommended to only allow notification based flows on devices and browsers that have successfully completed a dynamic link based flow. Setting up a unique device identifier is left to the RP to implement.

  • BASE/v3/certificatechoice/notification/document/:documentnumber

  • BASE/v3/signature/dynamic-link/document/:documentnumber

Signing without prior authentication

Without certificate query

In case no prior authentication has taken place, one should call the dynamic link based signature session endpoint for App2App and Web2App flows.

  • BASE/v3/signature/dynamic-link/etsi/:id-etsi-qcs-SemanticsId-Natural

With certificate query

Often though the certificate is required prior to the signing request. For this, RP should first call the notification based certificatechoice session endpoint.

  • BASE/v3/certificatechoice/notification/etsi/:id-etsi-qcs-SemanticsId-Natural

Immediately after receiving the response with the certificate, RP should call the notification based signature session endpoint. The Smart-ID app will wait for the signature session and return only after it has been completed.

  • BASE/v3/signature/notification/document/:documentnumber