Skip to main content
Version: v3

API Migration Guide

The following guide will help you migrate from API v2 to API v3.

Summary of changes

  • Endpoints are split up by eID provider.
  • All endpoints now require basic auth.
  • BankID QR is always enabled.
  • Triggering an BankID authentication using a SSN is only allowed when the user is on the phone with the partner. This functionality must be enabled before use.
  • Callbacks must be whitelisted.
  • Some payload properties have been added, renamed or removed.

List of changes

Start BankID authentication

Before (V2)

POST /v2/{{accountId}}/auth
Request body
{
"provider": "BankID",
"secretKey": "",
"pno": "",
"ipAddress": "",
"callbackUrl": "",
"allowFingerprint": true,
"enableQR": true,
"avsikt": "",
"intent": "",
"orgNumber": "",
"refID": ""
}
Response body
{
"orderRef": "",
"autoStartToken": "",
"qrStartToken": "",
"qrStartSecret": ""
}

After (V3)

In accordance with the latest changes to the BankID API, an authentication may no longer be triggered using a SSN. Instead, the BankID app must be triggered either on the same device using the "autoStartToken", or on a different device using a QR code. The "enableQR" property has therefore been been removed and is now always enabled.

POST /v3/bankid-se/auth
Authorization: Basic {{accountId}} {{secretKey}}
Request body
{
"ssn": "",
"ipAddress": "",
"pinRequired": true,
"intent": "",
"orgNumber": "",
"refId": ""
}
Response body
{
"id": "",
"autoStartToken": "",
"qrStartToken": "",
"qrStartSecret": "",
"refId": ""
}

Summary of changes

  • The path to the endpoint has changed
  • secretKey has been removed in favor of Basic Auth.
  • pno has been renamed to ssn and will no longer trigger BankID to start an authentication. Instead, the authentication will fail if the SSN of the authenticated user does not match the given SSN.
  • callbackUrl has been removed and must now be whitelisted by contacting us at support@idkollen.se.
  • allowFingerprint has been replaced with `pinRequired.
  • enableQR has been removed. It is now always enabled.
  • avsikt has been removed, use intent instead.
  • refID has been renamed to refId.
  • orderRef has been removed from the response. Use id instead.

Cancel BankID authentication

Before (V2)

POST /v2/{{accountId}}/cancel
{ 
"orderRef": ""
}

After (V3)

DELETE /v3/bankid-se/auth/{{id}}
Authorization: Basic {{accountId}} {{secretKey}}

Summary of changes

  • The path and method of the endpoint has changed and now includes the id.
  • The endpoint is now authenticated using Basic Auth.
  • The endpoint accepts no payload.

Get BankID authentication status

Before (V2)

GET /v2/{{accountId}}/collect/{{orderRef}}
{ 
"orderRef": "",
"status": "",
"pno": "",
"name": "",
"givenName": "",
"surname": "",
"hintCode": "",
"refID": ""
}

After (V3)

GET /v3/bankid-se/auth/{{id}}
Authorization: Basic {{accountId}} {{secretKey}}
{ 
"id": "",
"status": "",
"error": "",
"ssn": "",
"name": "",
"givenName": "",
"surname": "",
"refId": ""
}

Summary of changes

  • The path to the endpoint has changed
  • The endpoint is now authenticated using Basic Auth.
  • orderRef has been removed from the response. Use id instead.
  • The possible values of status has changed, see Collect.
  • The possible values of error has changed, see Collect.
  • hintCode has been removed.
  • refID has been renamed to refId.

Start BankID signing

Before (V2)

POST /v2/{{accountId}}/sign
Request body
{
"provider": "BankID",
"secretKey": "",
"pno": "",
"message": "",
"digest": "",
"ipAddress": "",
"callbackUrl": "",
"allowFingerprint": true,
"enableQR": true,
"orgNumber": "",
"refID": ""
}
Response body
{
"orderRef": "",
"autoStartToken": "",
"qrStartToken": "",
"qrStartSecret": ""
}

After (V3)

POST /v3/bankid-se/sign
Authorization: Basic {{accountId}} {{secretKey}}
Request body
{
"ssn": "",
"text": "",
"digest": "",
"ipAddress": "",
"pinRequired": true,
"orgNumber": "",
"refId": ""
}
Response body
{
"id": "",
"autoStartToken": "",
"qrStartToken": "",
"qrStartSecret": "",
"refId": ""
}

Summary of changes

  • The path to the endpoint has changed
  • secretKey has been removed in favor of Basic Auth.
  • pno has been renamed to ssn and will no longer trigger BankID to start an authentication. Instead, the authentication will fail if the SSN of the authenticated user does not match the given SSN.
  • callbackUrl has been removed and must now be whitelisted by contacting us at support@idkollen.se.
  • allowFingerprint has been replaced with `pinRequired.
  • enableQR has been removed. It is now always enabled.
  • refID has been renamed to refId.
  • orderRef has been removed from the response. Use id instead.

Cancel BankID signing

Before (V2)

POST /v2/{{accountId}}/cancel
{ 
"orderRef": ""
}

After (V3)

DELETE /v3/bankid-se/sign/{{id}}
Authorization: Basic {{accountId}} {{secretKey}}

Summary of changes

  • Cancelling a sign request now uses a separate endpoint.
  • The endpoint is now authenticated using Basic Auth.
  • The endpoint accepts no payload.

Get BankID signing status

Before (V2)

GET /v2/{{accountId}}/collect/{{orderRef}}
{ 
"orderRef": "",
"status": "",
"pno": "",
"name": "",
"givenName": "",
"surname": "",
"hintCode": "",
"refID": ""
}

After (V3)

GET /v3/bankid-se/sign/{{id}}
Authorization: Basic {{accountId}} {{secretKey}}
{ 
"id": "",
"status": "",
"error": "",
"ssn": "",
"name": "",
"givenName": "",
"surname": "",
"refId": ""
}

Summary of changes

  • Cancelling a sign request now uses a separate endpoint.
  • The endpoint is now authenticated using Basic Auth.
  • orderRef has been removed from the response. Use id instead.
  • The possible values of status has changed, see Collect.
  • The possible values of error has changed, see Collect.
  • hintCode has been removed.
  • refID has been renamed to refId.

Start Freja eID authentication

Before (V2)

POST /v2/{{accountId}}/auth
Request body
{
"provider": "freja",
"secretKey": "",
"pno": "",
"callbackUrl": "",
"minRegistrationLevel": "",
"orgNumber": "",
"refID": ""
}
Response body
{
"orderRef": ""
}

After (V3)

POST /v3/freja/auth
Authorization: Basic {{accountId}} {{secretKey}}
Request body
{
"ssn": "",
"minRegistrationLevel": "",
"orgNumber": "",
"refId": ""
}
Response body
{
"id": "",
"refId": ""
}

Summary of changes

  • The path to the endpoint has changed
  • secretKey has been removed in favor of Basic Auth.
  • pno has been renamed to ssn.
  • callbackUrl has been removed and must now be whitelisted by contacting us at support@idkollen.se.
  • refID has been renamed to refId.
  • orderRef has been removed from the response. Use id instead.

Cancel Freja eID authentication

Before (V2)

POST /v2/{{accountId}}/cancel
{ 
"orderRef": ""
}

After (V3)

DELETE /v3/freja/auth/{{id}}
Authorization: Basic {{accountId}} {{secretKey}}

Summary of changes

  • The path and method of the endpoint has changed and now includes the id.
  • The endpoint is now authenticated using Basic Auth.
  • The endpoint accepts no payload.

Get Freja eID authentication status

Before (V2)

GET /v2/{{accountId}}/collect/{{orderRef}}
{ 
"orderRef": "",
"status": "",
"pno": "",
"name": "",
"hintCode": ""
}

After (V3)

GET /v3/freja/auth/{{id}}
Authorization: Basic {{accountId}} {{secretKey}}
{ 
"id": "",
"status": "",
"error": "",
"ssn": "",
"name": "",
"givenName": "",
"surname": "",
"refId": ""
}

Summary of changes

  • The path to the endpoint has changed
  • The endpoint is now authenticated using Basic Auth.
  • orderRef has been removed from the response. Use id instead.
  • The possible values of status has changed, see Collect.
  • hintCode has been removed in favor of error.
  • pno has been renamed to ssn.
  • givenName and surname has been added.
  • refId has been added.

Start Freja eID signing

Before (V2)

POST /v2/{{accountId}}/sign
Request body
{
"provider": "freja",
"secretKey": "",
"pno": "",
"message": "",
"digest": "",
"callbackUrl": "",
"minRegistrationLevel": "",
"orgNumber": "",
"refID": ""
}
Response body
{
"orderRef": ""
}

After (V3)

POST /v3/freja/sign
Authorization: Basic {{accountId}} {{secretKey}}
Request body
{
"ssn": "",
"text": "",
"digest": "",
"minRegistrationLevel": "",
"orgNumber": "",
"refId": ""
}
Response body
{
"id": "",
"refId": ""
}

Summary of changes

  • The path to the endpoint has changed
  • secretKey has been removed in favor of Basic Auth.
  • pno has been renamed to ssn.
  • callbackUrl has been removed and must now be whitelisted by contacting us at support@idkollen.se.
  • refID has been renamed to refId.
  • orderRef has been removed from the response. Use id instead.

Cancel Freja eID signing

Before (V2)

POST /v2/{{accountId}}/cancel
{ 
"orderRef": ""
}

After (V3)

DELETE /v3/freja/sign/{{id}}
Authorization: Basic {{accountId}} {{secretKey}}

Summary of changes

  • Cancelling a sign request now uses a separate endpoint.
  • The endpoint is now authenticated using Basic Auth.
  • The endpoint accepts no payload.

Get Freja eID signing status

Before (V2)

GET /v2/{{accountId}}/collect/{{orderRef}}
{ 
"orderRef": "",
"status": "",
"pno": "",
"name": "",
"hintCode": ""
}

After (V3)

GET /v3/freja/sign/{{id}}
Authorization: Basic {{accountId}} {{secretKey}}
{ 
"id": "",
"status": "",
"error": "",
"ssn": "",
"name": "",
"givenName": "",
"surname": "",
"refId": ""
}

Summary of changes

  • The path to the endpoint has changed
  • The endpoint is now authenticated using Basic Auth.
  • orderRef has been removed from the response. Use id instead.
  • The possible values of status has changed, see Collect.
  • hintCode has been removed in favor of error.
  • pno has been renamed to ssn.
  • givenName and surname has been added.
  • refId has been added.