/auth
Initiates an authentication 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 auth
POST /rp/v6.0/auth HTTP/1.1
Content-Type: application/json
Host: appapi2.bankid.com
{
"endUserIp": "194.168.2.25"
}
Parameters for auth
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 auth order must be performed. See section Requirements below for more details. |
|
userVisibleData | Optional |
Text displayed to the user during authentication with BankID, with the purpose of providing context for the authentication and to enable users to detect identification errors and averting fraud attempts. 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—1 500 characters after base 64 encoding. |
|
userNonVisibleData | Optional |
Data is not displayed to the user. String. The value must be base 64-encoded. 1-1 500 characters after base 64-encoding. |
|
userVisibleDataFormat | Optional |
If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which, will potentially make the text displayed to the user nicer to look at. 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 auth order must be performed. See section Requirements below for more details.
Optional
Text displayed to the user during authentication with BankID, with the purpose of providing context for the authentication and to enable users to detect identification errors and averting fraud attempts. 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—1 500 characters after base 64 encoding.
Optional
Data is not displayed to the user. String. The value must be base 64-encoded. 1-1 500 characters after base 64-encoding.
Optional
If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which, will potentially make the text displayed to the user nicer to look at. 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. 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.
"<"no value">" – 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 auth
POST /rp/v6.0/auth HTTP/1.1
Content-Type: application/json
Host: appapi2.bankid.com
{
"endUserIp": "192.168.0.1"
"requirement": {"pinCode":true}
}
Example – certificatePolicies for auth with Mobile BankID
POST /rp/v6.0/auth HTTP/1.1
Content-Type: application/json
Host: appapi2.bankid.com
{
"endUserIp": "192.168.0.1"
"requirement": {"certificatePolicies":["1.2.752.78.1.5"]}
}
Response from auth
Name | Value |
---|---|
orderRef |
Used to collect the status of the order. String. |
autoStartToken |
Used to compile the start url according to launching. 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 according to launching. String.
qrStartToken
Used to compute the animated QR code. String.
qrStartSecret
Used to compute the animated QR code. String.
Example response from auth
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"
}