/sign
Initiates an signing order. Use the collect method to query the status of the order. If the request is successful the response includes orderRef, autoStartToken, qrStartToken and qrStartSecret (see table below for details).
Example – request sign
POST /rp/v6.0/sign HTTP/1.1
Content-Type: application/json
Host: appapi2.bankid.com
{
"endUserIp": "194.168.2.25",
"userVisibleData": "IFRoaXMgaXMgYSBzYW1wbGUgdGV4dCB0byBiZSBzaWduZWQ=",
}
Parameters for sign
Name | Required |
---|---|
endUserIp | Required |
The user IP address as seen by RP. String. IPv4 and IPv6 is allowed. Correct IP address must be the IP address representing the user agent (the end user device) as seen by the RP. In case of inbound proxy, special considerations may need to be taken into account to get the correct address. In some use cases the IP address is not available, for instance in voice-based services. In these cases, the internal representation of those systems’ IP address may be used. |
|
requirement | Optional |
Requirements on how the sign order must be performed. See the section Requirements below for more details. |
|
userVisibleData | Required |
Text to be displayed to the user. String. The text can be formatted using CR, LF and CRLF for new lines. The text must be encoded as UTF-8 and then base 64 encoded. 1 – 40,000 characters after base 64 encoding. |
|
userNonVisibleData | Optional |
Data is not displayed to the user. String. The value must be base 64 encoded. 1 – 200,000 characters after base 64-encoding. |
|
userVisibleDataFormat | Optional |
If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which potentially make for a more pleasant user experience. For further information of formatting options, see this guide. |
Name
Required
The user IP address as seen by RP. String. IPv4 and IPv6 is allowed.
Correct IP address must be the IP address representing the user agent (the end user device) as seen by the RP. In case of inbound proxy, special considerations may need to be taken into account to get the correct address.
In some use cases the IP address is not available, for instance in voice-based services. In these cases, the internal representation of those systems’ IP address may be used.
Optional
Requirements on how the sign order must be performed. See the section Requirements below for more details.
Required
Text to be displayed to the user. String.
The text can be formatted using CR, LF and CRLF for new lines. The text must be encoded as UTF-8 and then base 64 encoded. 1 – 40,000 characters after base 64 encoding.
Optional
Data is not displayed to the user. String.
The value must be base 64 encoded. 1 – 200,000 characters after base 64-encoding.
Optional
If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which potentially make for a more pleasant user experience. For further information of formatting options, see this guide.
Requirements
RP may use the requirement parameter to describe how a signature must be created and verified. A typical use case is to require Mobile BankID or a certain card reader. A requirement can be set for both auth and sign orders. The following table describes requirements, their possible values and defaults.
Name | Value | Default |
---|---|---|
pinCode |
Users are required to sign the transaction with their PIN code, even if they have biometrics activated. |
False, the user is not required to use pin code. |
mrtd |
Boolean. If present, and set to "true", the client needs to provide MRTD (Machine readable travel document) information to complete the order.Only Swedish passports and national ID cards are supported. |
The client does not need to provide MRTD information to complete the order. |
cardReader |
|
No card reader required. |
certificatePolicies |
The oid in certificate policies in the user certificate. List of String. The values for production BankIDs are:
The values for test BankIDs are:
|
If no set certificate policies, the following are default in the: Production system
Test system:
If any certificate policy is set all default policies are dismissed. |
personalNumber |
A personal identification number to be used to complete the transaction. If a BankID with another personal number attempts to sign the transaction, it fails. |
pinCode
Users are required to sign the transaction with their PIN code, even if they have biometrics activated.
False, the user is not required to use pin code.
mrtd
Boolean. If present, and set to "true", the client needs to provide MRTD (Machine readable travel document) information to complete the order.Only Swedish passports and national ID cards are supported.
The client does not need to provide MRTD information to complete the order.
cardReader
"class1" (default) – The transaction must be performed using a card reader where the PIN code is entered on a computer keyboard, or a card reader of higher class.
"class2" – The transaction must be performed using a card reader where the PIN code is entered on the reader, or a reader of higher class.
– defaults to "class1". This condition should be combined with a certificatePolicies for a smart card to avoid undefined behaviour.
No card reader required.
certificatePolicies
The oid in certificate policies in the user certificate. List of String.
One wildcard ”” is allowed from position 5 and forward ie. 1.2.752.78.
The values for production BankIDs are:
"1.2.752.78.1.1" - BankID on file
"1.2.752.78.1.2" - BankID on smart card
"1.2.752.78.1.5" - Mobile BankID
The values for test BankIDs are:
"1.2.3.4.5" - BankID on file
"1.2.3.4.10" - BankID on smart card
"1.2.3.4.25" - Mobile BankID
“1.2.752.60.1.6” - Test BankID for some BankID Banks
If no set certificate policies, the following are default in the:
Production system
1.2.752.78.1.1
1.2.752.78.1.2
1.2.752.78.1.5
1.2.752.71.1.3
Test system:
1.2.3.4.5
1.2.3.4.10
1.2.3.4.25
1.2.752.60.1.6
1.2.752.71.1.3
If any certificate policy is set all default policies are dismissed.
personalNumber
A personal identification number to be used to complete the transaction. If a BankID with another personal number attempts to sign the transaction, it fails.
Example – pinCode for sign:
POST /rp/v6.0/sign HTTP/1.1
Content-Type: application/json
Host: appapi2.bankid.com
{
"endUserIp": "192.168.0.1"
"userVisibleData": "IFRoaXMgaXMgYSBzYW1wbGUgdGV4dCB0byBiZSBzaWduZWQ=",
"requirement": {
"pinCode":true,
}
}
Example – certificatePolicies for sign with Mobile BankID
POST /rp/v6.0/sign HTTP/1.1
Content-Type: application/json
Host: appapi2.bankid.com
{
"endUserIp": "192.168.0.1"
"userVisibleData": "IFRoaXMgaXMgYSBzYW1wbGUgdGV4dCB0byBiZSBzaWduZWQ=",
"requirement": {"certificatePolicies":["1.2.752.78.1.5"]}
}
Response from sign
Name | Value |
---|---|
orderRef |
Used to collect the status of the order. String. |
autoStartToken |
Used to compile the start url. String. |
qrStartToken |
Used to compute the animated QR code. String. |
qrStartSecret |
Used to compute the animated QR code. String. |
orderRef
Used to collect the status of the order. String.
autoStartToken
Used to compile the start url. String.
qrStartToken
Used to compute the animated QR code. String.
qrStartSecret
Used to compute the animated QR code. String.
Example – response from sign
HTTP/1.1 200 OK
Content-Type: application/json
{
"orderRef":"131daac9-16c6-4618-beb0-365768f37288",
"autoStartToken":"7c40b5c9-fa74-49cf-b98c-bfe651f9a7c6",
"qrStartToken":"67df3917-fa0d-44e5-b327-edcc928297f8",
"qrStartSecret":"d28db9a7-4cde-429e-a983-359be676944c"
}