Authentication
The POST /v3/bankid-se/auth endpoint is used to start an authentication using BankID (SE).
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"
}
Start authentication
| 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 | Custom callback URL, must be whitelisted. 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.
{
"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 user over the phone.
This method will trigger the users BankID app 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.
{
"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 |
Fetch result
As an alternative to receiving a callback from IDkollen on successful or failed requests, you can use the
GET /v3/bankid-se/auth/{{id}} endpoint to check the status of an auth request.
NOTE: This endpoint is rate limited to one request per second.
GET /v3/bankid-se/auth/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
This endpoint will respond with a HTTP status of 404 if the authentication session has expired.
The status of an authentication can be either one of: PENDING, COMPLETED or FAILED.
Pending
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "PENDING",
"hintCode": "started"
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
| hintCode | See the section hintCode for pending orders at https://www.bankid.com/utvecklare/guider/teknisk-integrationsguide/graenssnittsbeskrivning/collect. |
Completed
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "COMPLETED",
"ssn": "YYYYMMDDXXXX",
"name": "Firstname Lastname",
"givenName": "Firstname",
"surname": "Lastname",
"certStartDate": "2020-01-01",
"companySignatoryText": "X är företrädare för Y..."
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
| ssn | A Swedish personal identification number to be used to complete the transaction. |
| name | The full name of the authenticated user. |
| givenName | The given name of the authenticated user. |
| surname | The surname of the authenticated user. |
| certStartDate | The date the BankID was issued to the user. |
| companySignatoryText | A text describing whether the authenticated user is a signatory for the given organisation number. |
Failed
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "FAILED",
"error": "INVALID_ID"
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
| error | An error code describing the reason for why the authentication failed. |
The error may be one of the following values:
| Code | Description |
|---|---|
| AUTH_FAILED | A generic code for any kind of failure. |
| CANCELLED | The authentication was cancelled either by the user or the partner. |
| INVALID_ID | The ID has expired or is otherwise invalid. |
| INTERNAL_ERROR | An internal error occurred causing the authentication to fail. |
| SESSION_TIMEOUT | The authentication expired or timed out. |
| UNSUPPORTED_CLIENT | The client used for the authentication is not supported. |
New error codes may be added in the future without prior notice. The partner should therefore handle unknown error codes in their implementations.
Cancel authentication
The DELETE /v3/bankid-se/auth/{{id}} endpoint is used to cancel an ongoing BankID authentication.
DELETE /v3/bankid-se/auth/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
IDkollen will respond with HTTP status 204 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.