`authentication` session

The signature protocol ACSP_V1 must be used for authentication.

Dynamic link based `authentication` session

Dynamic link based authentication endpoints
Method	URL
`POST`	`BASE/v3/authentication/dynamic-link/etsi/:id-etsi-qcs-SemanticsId-Natural`
`POST`	`BASE/v3/authentication/dynamic-link/document/:documentnumber`
`POST`	`BASE/v3/authentication/dynamic-link/anonymous`

This method is the main entry point to authentication logic for the dynamic link based flows. In contrast to the notification based flows, an "anonymous" endpoint is provided. When that endpoint is used, RP learns the user’s identity only after the signing has been completed and the session result is returned to the RP.

Error conditions

HTTP error code 403 - Relying Party has no permission to issue the request. This may happen when: Relying Party has no permission to invoke operations on accounts with ADVANCED certificates. Relying Party has no permission to use requested capability.
HTTP error code 404 - object described in URL was not found, essentially meaning that the user does not have an account in Smart-ID system.

Request parameters

Dynamic link based authentication request parameters
Parameter	Type	Mandatory	Description
`relyingPartyUUID`	string	+	UUID of Relying Party.
`relyingPartyName`	string	+	RP friendly name, one of those configured for particular RP. Limited to 32 bytes in UTF-8 encoding.
`certificateLevel`	string		Level of certificate requested. `ADVANCED`/`QUALIFIED`, `QUALIFIED`.
`signatureProtocol`	string	+	Signature protocol. Describes the algorithm how signature is produced and the `signatureProtocolParameters` object. Currently, the only allowed value is: `ACSP_V1` - Data structure V1 with authentication context to be signed. See section `ACSP_V1`.
`signatureProtocolParameters`	object	+	Signature protocol. An object describing the parameters of the signature algorithm. Its structure depends on the `signatureProtocol` used. See ACSP_V1 parameters table.
`nonce`	string		Random string, up to 30 characters. If present, must have at least 1 character.
`allowedInteractionsOrder`	array of objects	+	See section available interactions.
`requestProperties`	object		A request properties object. Currently, only one property is supported: `shareMdClientIpAddress` - Whether the RP API server should share user mobile device IP address with the RP. By default it is set to `false`. The RP must have proper privilege to use this property. See section IP sharing for details.
`capabilities`	array		Used only when agreed with Smart-ID provider. When omitted request capabilities are derived from `certificateLevel` parameter.

Dynamic link based authentication request example

{
  "relyingPartyUUID": "1f1bfa89-4f8b-420a-a98e-fb3a161a30bc",
  "relyingPartyName": "DEMO",
  "certificateLevel": "QUALIFIED",
  "signatureProtocol": "ACSP_V1",
  "signatureProtocolParameters": {
    "randomChallenge": "ZHNmYmhkZmdoZGcgZmRmMTQ0NTM...",
    "signatureAlgorithm": "sha256WithRSAEncryption"
  },
  "nonce": "d8XkbEnA0WsE0PvBZZoxGnPI4ml9qk",
  "allowedInteractionsOrder": [
    {
      "type": "displayTextAndPIN",
      "displayText60": "Short description of the transaction context"
    }
  ],
  "requestProperties": {
    "shareMdClientIpAddress": true
  }
}

Response structure

Successful dynamic link based `authentication` session creation response parameters
Parameter	Type	Mandatory	Description
`sessionID`	string	+	A string that can be used to request the operation result.
`sessionToken`	string	+	Unique random value that will be used to connect this login attempt between the relevant parties (RP, RP-API, mobile app).
`sessionSecret`	string	+	Base64-encoded random key value that should be kept in secret and should be shared only between the RP backend and RP-API server.

Dynamic link based authentication session creation response

{
  "sessionID": "de305d54-75b4-431b-adb2-eb6b9e546014",
  "sessionToken": "hyBdQYUeQtvXEPqWC7K8a97L",
  "sessionSecret": "dztL7Ur49D/YYgUzYl4sMg=="
}

Notification based `authentication` session

Notification based authentication endpoints
Method	URL
`POST`	`BASE/v3/authentication/notification/etsi/:id-etsi-qcs-SemanticsId-Natural`
`POST`	`BASE/v3/authentication/notification/document/:documentnumber`

This method is the main entry point to authentication logic for the notification based flows. It selects user’s authentication key as the one to be used in the process.

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.

Error conditions

HTTP error code 403 - Relying Party has no permission to issue the request. This may happen when: Relying Party has no permission to invoke operations on accounts with ADVANCED certificates. Relying Party has no permission to use requested capability.
HTTP error code 404 - object described in URL was not found, essentially meaning that the user does not have an account in Smart-ID system.

Request parameters

Notification based authentication request parameters
Parameter	Type	Mandatory	Description
`relyingPartyUUID`	string	+	UUID of Relying Party.
`relyingPartyName`	string	+	RP friendly name, one of those configured for particular RP. Limited to 32 bytes in UTF-8 encoding.
`certificateLevel`	string		Level of certificate requested. `ADVANCED`/`QUALIFIED`, `QUALIFIED`.
`signatureProtocol`	string	+	Signature protocol. Describes the algorithm how signature is produced and the `signatureProtocolParameters` object. Currently, the only allowed value is: `ACSP_V1` - Data structure V1 with authentication context to be signed. See section `ACSP_V1`.
`signatureProtocolParameters`	object	+	Signature protocol. An object describing the parameters of the signature algorithm. Its structure depends on the `signatureProtocol` used. See ACSP_V1 parameters table.
`nonce`	string		Random string, up to 30 characters. If present, must have at least 1 character.
`allowedInteractionsOrder`	object	+	See section available interactions.
`requestProperties`	object		A request properties object. Currently, only one property is supported: `shareMdClientIpAddress` - Whether the RP API server should share user mobile device IP address with the RP. By default it is set to `false`. The RP must have proper privilege to use this property. See section IP sharing for details.
`capabilities`	array		Used only when agreed with Smart-ID provider. When omitted request capabilities are derived from `certificateLevel` parameter.

Notification based authentication request example

{
  "relyingPartyUUID": "1f1bfa89-4f8b-420a-a98e-fb3a161a30bc",
  "relyingPartyName": "DEMO",
  "certificateLevel": "QUALIFIED",
  "signatureProtocol": "ACSP_V1",
  "signatureProtocolParameters": {
    "randomChallenge": "ZHNmYmhkZmdoZGcgZmRmMTQ0NTM...",
    "signatureAlgorithm": "sha256WithRSAEncryption"
  },
  "nonce": "d8XkbEnA0WsE0PvBZZoxGnPI4ml9qk",
  "allowedInteractionsOrder": [
    {
      "type": "displayTextAndPIN",
      "displayText60": "Short description of the transaction context"
    }
  ],
  "requestProperties": {
    "shareMdClientIpAddress": true
  }
}

Response structure

Notification based `authentication` session creation response parameters
Parameter	Type	Mandatory	Description
`sessionID`	string	+	A string that can be used to request the operation result.
`vc`	string	+	Object describing the VC code to be displayed by RP. See section VC codes.
`vc.type`	string	+	Type of the VC code. Currently, the only allowed type is `alphaNumeric4`. Note that the type is "alphaNumeric4" to refer to the fact that in the future the 4-symbol code might also contain letters. For the time being, only numeric values are returned for technical reasons. This may change in the future, so RPs should make no assumptions about it containing numeric data only!
`vc.value`	string	+	Value of the VC code.

Notification based authentication session creation response

{
  "sessionID": "de305d54-75b4-431b-adb2-eb6b9e546015",
  "vc": {
    "type": "alphaNumeric4",
    "value": "4927"
  }
}

authentication session

Dynamic link based authentication session

Error conditions

Request parameters

Response structure

Notification based authentication session

Error conditions

Request parameters

Response structure

`authentication` session

Dynamic link based `authentication` session

Notification based `authentication` session