Authentication

The POST /v3/bankid-se/auth endpoint is used to start an authentication using BankID.

POST /v3/bankid-se/auth
Authorization: Basic ${ base64(accountId + ':' + secretKey) }

{
  "ssn": "YYYYMMDDXXXX",
  "ipAddress": "8.8.8.8",
  "pinRequired": true,
  "intent": "Intention text",
  "orgNumber": "559000-0948",
  "callbackUrl": "https://...",
  "refId": "12398698"
}

Parameter	Required	Description
ssn	No	A Swedish personal identification number to be used to complete the transaction. If a BankID with another personal number attempts to authenticate, it fails.
ipAddress	No	The IP-address of the end user, or as close to the end user as possible.
pinRequired	No	Require users to sign using their PIN code, even if they have biometrics enabled.
intent	No	Text to be displayed in the users BankID app during authentication, for purposes of adding an intention for requesting the authentication. Max 1500 characters after base64. Formatting options can be found here: https://www.bankid.com/en/utvecklare/guider/formatera-text/syntax-specialtecken-atergivning
orgNumber	No	Organizational number, 11 digits. Used to perform checks for company signatory. To enable this feature, contact IDkollen.
callbackUrl	No	See Callback.
refId	No	Reference ID which will be included in a Collect and in the callback.

IDkollen will respond with HTTP status 201 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.

HTTP/2.0 201 Created
{
  "id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
  "refId": "12398698",
  "status": "PENDING",
  "autoStartToken": "6e8fdb9e-4cc7-42a7-9ce7-59947aeec6e6",
  "qrStartToken": "8b9c387f-8948-4b53-b6a5-519eee985d44",
  "qrStartSecret": "f47d75e0-6662-4bb9-9b09-ca37849ef1e0",
  "hintCode": "started"
}

Property	Description
id	Authentication id, used to cancel or get the status of this authentication request.
refId	The refId given in the request, if any.
autoStartToken	A token used to launch the BankID app on the same device. See https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide/programstart
qrStartToken	A token used, in combination with the `qrStartSecret`, to generate an animated QR code to authenticate using BankID on another device. See https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide/qrkoder
qrStartSecret	Used to animate the QR code.
hintCode	A string (potentially null) that can be used to provide the user with instructions. See 'hintCode for pending orders' at https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide/graenssnittsbeskrivning/collect

Phone Auth

The POST /v3/bankid-se/phone/auth endpoint can be used to start an authentication using BankID when the user is talking to the partner over the phone. This method will trigger BankID to start the authentication using an SSN alone.

POST /v3/bankid-se/phone/auth
Authorization: Basic ${ base64(accountId + ':' + secretKey) }

{
  "ssn": "YYYYMMDDXXXX",
  "callInitiator": "USER",
  "pinRequired": true,
  "intent": "Intention text",
  "orgNumber": "559000-0948",
  "callbackUrl": "https://...",
  "refId": "12398698"
}

Parameter	Required	Description
ssn	Yes	The Swedish personal identification number of the user to authenticate.
callInitiator	Yes	Can be one of: 'USER' or 'RP'. Indicates whether the user or the RP initiated the phone call.
pinRequired	No	Require users to sign using their PIN code, even if they have biometrics enabled.
intent	No	Text to be displayed in the users BankID app during authentication, for purposes of adding an intention for requesting the authentication. Max 1500 characters after base64. Formatting options can be found here: https://www.bankid.com/en/utvecklare/guider/formatera-text/syntax-specialtecken-atergivning
orgNumber	No	Organizational number, 11 digits. Used to perform checks for company signatory. To enable this feature, contact IDkollen.
callbackUrl	No	See Callback.
refId	No	Reference ID which will be returned with the status and included in the callback.

IDkollen will respond with HTTP status 201 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.

HTTP/2.0 201 Created
{
  "id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
  "refId": "12398698",
  "status": "PENDING",
  "hintCode": "started"
}

Property	Description
id	Authentication id, used to cancel or get the status of this authentication request.
refId	The refId given in the request, if any.
hintCode	A string (potentially null) that can be used to provide the user with instructions. See 'hintCode for pending orders' at https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide/graenssnittsbeskrivning/collect

Phone Auth​

Phone Auth