`certificatechoice` session

This method returns the signing certificate of the user and if needed queries the user which device they intend to use in the following signature session.

Having a correct certificate is needed for giving signatures under *AdES schemes. The method should not be used if the signature scheme does not mandate presence of the certificate in the document structure that is to be signed.

A Smart-ID user can have multiple active accounts and document number is the unique identifier for a specific Smart-ID account.

If an RP has previously done authentication flow for a user, the next signature request should use certificatechoice with the obtained document number, so that the RP can immediately get user’s correct certificate without interaction from the user.

In case the certificatechoice with the identifier is used, e.g. in case of a signature request with no prior authentication, the RP must immediately use the notification based signature session after receiving the certificate. This is because when the Smart-ID app receives a certificatechoice session, it will service the request and then stay in the foreground and wait for the notification based signature session for a seamless user experience.

A quick guide to choosing which certificatechoice endpoint to use:

if a prior authentication was recently completed and a documentnumber was received, use the certificatechoice endpoint with documentnumber;
if some time has passed from last authentication (more than a day), it is recommended to use the certificatechoice endpoint referencing a user identifier, not a specific account (and not refer to a specific documentnumber);
if there is no prior authentication, the certificatechoice endpoint referencing a user identifier must be used.

The method accepts QSCD as a certificate level parameter. This is a shortcut marking a certificate of QUALIFIED level which is also QSCD-capable. ADVANCED certificates cannot be QSCD-capable.

`certificatechoice` session endpoints

`certificatechoice` session endpoints
Method	URL
`POST`	`BASE/v3/certificatechoice/notification/etsi/:id-etsi-qcs-SemanticsId-Natural`
`POST`	`BASE/v3/certificatechoice/notification/document/:documentnumber`

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

`certificatechoice` session 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`/`QSCD`, defaults to `QUALIFIED`.
`nonce`	string		Random string, up to 30 characters. If present, must have at least 1 character.
`capabilities`	array		Used only when agreed with Smart-ID provider. When omitted request capabilities are derived from `certificateLevel` parameter.
`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.

certificatechoice session request example

{
  "relyingPartyUUID": "1f1bfa89-4f8b-420a-a98e-fb3a161a30bc",
  "relyingPartyName": "DEMO",
  "certificateLevel": "QUALIFIED",
  "nonce": "d8XkbEnA0WsE0PvBZZoxGnPI4ml9qk",
  "requestProperties": {
    "shareMdClientIpAddress": true
  }
}

Example response

certificatechoice session response

{
  "sessionID": "de305d54-75b4-431b-adb2-eb6b9e546014"
}

Response on successful session creation

Successful `certificatechoice` session creation response parameters
Parameter	Type	Mandatory	Description
`sessionID`	string	+	A string that can be used to request the operation result.

Successful session creation response

{
  "sessionID": "de305d54-75b4-431b-adb2-eb6b9e546014"
}