session status

session status endpoint
Method URL

GET

BASE/v3/session/:sessionId
session status query parameter
Parameter Type Mandatory Description

timeoutMs

integer

Request long poll timeout value in milliseconds. The upper bound of timeout: 120000, minimum 1000. If not specified by the API client in the request, a value halfway between maximum and minimum is used.

This method can be used to retrieve session result from Smart-ID backend.

This is a long poll method, meaning it might not return until a timeout expires. Caller can tune the request parameters inside the bounds set by service operator.

Example URL:

https://https://rp-api.smart-id.com/v3/session/de305d54-75b4-431b-adb2-eb6b9e546016?timeoutMs=10000

Error conditions

  • HTTP error code 404 - session does not exist or has expired.

Response structure

session status response
Parameter Type Mandatory Description

state

string

+

State of request. RUNNING/COMPLETE. There are only two possible status codes for now.

result

object

Structure describing end result, may be empty or missing when still running.

result.endResult

string

+

End result of the transaction (OK if session was completed successfully). Refer to the subsection below for all possible values.

result.documentNumber

string

for OK

Document number, can be used in further signature and authentication requests to target the same device.

signatureProtocol

string

Signature protocol. Possible values:

  • ACSP_V1 - signature protocol used for the authentication sessions.

  • RAW_DIGEST_SIGNATURE - signature protocol used for the signature sessions.

See Signature protocols for additional details.

signature

object

Structure describing the signature result, if any. The structure depends on the signature protocol used.

cert

object

for OK

Structure describing the certificate related to the request.

cert.value

string

+

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.

cert.certificateLevel

string

+

Level of Smart-ID certificate: ADVANCED or QUALIFIED

ignoredProperties

array

Any values from requestProperties that were unsupported or ignored.

interactionFlowUsed

string

for OK

Name of interaction used. See section available interactions.

deviceIpAddress

string

IP address of the mobile device. Is present only when it has been previously requested by the RelyingParty within the session creation parameters. See section IP sharing.

Signature body for RAW_DIGEST_SIGNATURE protocol

Signature body for RAW_DIGEST_SIGNATURE in session response
Parameter Type Mandatory Description

value

string

+

Signature value, base64 encoded.

signatureAlgorithm

string

+

The signature algorithm that was used to generate the signature based on the digest. See Supported signature algorithms.

Signature body for ACSP_V1 protocol

The following table describes the signature body for ACSP_V1 protocol that the RP will receive in the session response. Notice that the actual object that was signed is not present — it needs to be compiled by the RP using the RP-provided randomChallenge and the serverRandom returned in this response. This re-constructed object must then be used to validate the signature. See ACSP_V1 for details.

Signature body for ACSP_V1 in session response
Parameter Type Mandatory Description

value

string

+

Signature value, base64 encoded.

signatureAlgorithm

string

+

Signature creation scheme that was used for creating the signature. See Supported signature algorithms.

serverRandom

string

+

A random value of 24 or more characters from Base64 alphabet, which is generated at RP API service side. RP must validate that the value contains only valid Base64 characters. This value will be returned from RP API and RelyingParties must use it exactly as it was returned during the validation of signature. There are not any guarantees that the returned value length is the same in each call of the RP API.
Successful response when still waiting for user’s response
{
  "state": "RUNNING"
}
Successful response after completion, dynamic flow, protocol ACSP_V1 (IP sharing is enabled)
{
  "state": "COMPLETE",
  "result": {
    "endResult": "OK",
    "documentNumber": "PNOEE-372...."
  },
  "signatureProtocol": "ACSP_V1",
  "signature": {
    "serverRandom": "B+C9XVjIAZnCHH9vfBSv...",
    "value": "B+A9CfjIBZnDHHav3B4F...",
    "signatureAlgorithm": "sha512WithRSAEncryption"
  },
  "cert": {
    "value": "B+C9XVjIAZnCHH9vfBSv...",
    "certificateLevel": "QUALIFIED"
  },
  "interactionFlowUsed": "displayTextAndPIN",
  "deviceIpAddress": "203.0.113.34"
}
Successful response after completion, notification based flow, protocol RAW_DIGEST_SIGNATURE (IP sharing is enabled)
{
  "state": "COMPLETE",
  "result": {
    "endResult": "OK",
    "documentNumber": "PNOEE-372...."
  },
  "signatureProtocol": "RAW_DIGEST_SIGNATURE",
  "signature": {
    "value": "B+A9CfjIBZnDHHav3B4F...",
    "signatureAlgorithm": "sha512WithRSAEncryption"
  },
  "cert": {
    "value": "B+C9XVjIAZnCHH9vfBSv...",
    "certificateLevel": "QUALIFIED"
  },
  "interactionFlowUsed": "displayTextAndPIN",
  "deviceIpAddress": "203.0.113.34"
}

session status end result codes

  • OK - session was completed successfully, there is a certificate, document number and possibly signature in return structure.

  • USER_REFUSED - user refused the session.

  • 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 must 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 allowedInteractionsOrder interactions.

  • USER_REFUSED_CERT_CHOICE - user has multiple accounts and pressed Cancel on device choice screen on any device.

  • USER_REFUSED_DISPLAYTEXTANDPIN - user pressed Cancel on PIN screen. Can be from the most common displayTextAndPIN flow or from verificationCodeChoice flow when user chosen the right code and then pressed cancel on PIN screen.

  • USER_REFUSED_VC_CHOICE - user cancelled verificationCodeChoice screen.

  • USER_REFUSED_CONFIRMATIONMESSAGE - user cancelled on confirmationMessage screen.

  • USER_REFUSED_CONFIRMATIONMESSAGE_WITH_VC_CHOICE - user cancelled on confirmationMessageAndVerificationCodeChoice screen.