Skip to main content

API v3 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.
  • Callback URLs must be whitelisted, either by domain or full path.
  • 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 removed and is now always enabled.

POST /v3/bankid-se/auth
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
Request body​
{
  "ssn": "",
  "ipAddress": "",
  "callbackUrl": "",
  "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 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. Note the lowercase 'd'.
  • 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 ${ base64(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 ${ base64(accountId + ':' + secretKey) }
{
  "id": "",
  "status": "",
  "error": "",
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "hintCode": "",
  "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 is only available when status is PENDING, on failure refer to the error parameter.
  • refID has been renamed to refId. Note the lowercase 'd'.

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 ${ base64(accountId + ':' + secretKey) }
Request body​
{
  "ssn": "",
  "text": "",
  "digest": "",
  "ipAddress": "",
  "callbackUrl": "",
  "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 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. Note the lowercase 'd'.
  • 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 ${ base64(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 ${ base64(accountId + ':' + secretKey) }
{
  "id": "",
  "status": "",
  "error": "",
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "hintCode": "",
  "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.
  • hintCode is only available when status is PENDING, on failure refer to the error parameter.
  • refID has been renamed to refId. Note the lowercase 'd'.

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 ${ base64(accountId + ':' + secretKey) }
Request body​
{
  "ssn": "",
  "callbackUrl": "",
  "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 must now be whitelisted by contacting us at support@idkollen.se.
  • refID has been renamed to refId. Note the lowercase 'd'.
  • 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 ${ base64(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 ${ base64(accountId + ':' + secretKey) }
{
  "id": "",
  "status": "",
  "error": "",
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "hintCode": "",
  "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 is only available when status is PENDING, on failure refer to the error parameter.
  • 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 ${ base64(accountId + ':' + secretKey) }
Request body​
{
  "ssn": "",
  "text": "",
  "digest": "",
  "callbackUrl": "",
  "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 must now be whitelisted by contacting us at support@idkollen.se.
  • refID has been renamed to refId. Note the lowercase 'd'.
  • 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 ${ base64(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 ${ base64(accountId + ':' + secretKey) }
{ 
  "id": "", 
  "status": "", 
  "error": "",
  "ssn": "", 
  "name": "",
  "givenName": "",
  "surname": "",
  "hintCode": "",
  "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 is only available when status is PENDING, on failure refer to the error parameter.
  • pno has been renamed to ssn.
  • givenName and surname has been added.
  • refId has been added.

Start BankID (NO) authentication​

Before (V2)​

POST /v2/{{accountId}}/no/login
Request body​
{
  "requestSSN": true,
  "refID": "",
  "secretKey": ""
}
Response body​
{
  "loginLink": ""
}

After (V3)​

POST /v3/bankid-no/auth
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
Request body​
{
  "requestSsn": true,
  "refId": ""
}
Response body​
{
  "id": "",
  "refId": "",
  "url": ""
}

Summary of changes​

  • The path to the endpoint has changed
  • secretKey has been removed in favor of Basic Auth.
  • loginLink has been renamed to url.
  • requestSSN has been renamed to requestSsn. Note the different casing.
  • refID has been renamed to refId. Note the lowercase 'd'.

Get BankID (NO) authentication status​

Before (V2)​

GET /v2/{{accountId}}/no/verify/{{code}}
{
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "birthDate": "",
  "refID": ""
}

After (V3)​

GET /v3/bankid-no/auth/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
  "id": "",
  "status": "",
  "error": "",
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "birthDate": "",
  "refId": ""
}

Summary of changes​

  • The path to the endpoint has changed
  • The endpoint is now authenticated using Basic Auth.
  • The redirect request parameter code is renamed to id.
  • The possible values of status has changed, see Collect.
  • refID has been renamed to refId. Note the lowercase 'd'.

Start BankID (NO) signing​

Before (V2)​

POST /v2/{{accountId}}/no/sign
Request body​
{
  "secretKey": "",
  "signText": "",
  "refID": ""
}
Response body​
{
  "signLink": ""
}

After (V3)​

POST /v3/bankid-no/sign
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
Request body​
{
  "text": "",
  "refId": ""
}
Response body​
{
  "id": "",
  "refId": "",
  "url": ""
}

Summary of changes​

  • The path to the endpoint has changed
  • secretKey has been removed in favor of Basic Auth.
  • signLink has been renamed to url.
  • signText has been renamed to text.
  • refID has been renamed to refId. Note the lowercase 'd'.

Get BankID (NO) signing status​

Before (V2)​

GET /v2/{{accountId}}/no/verify/{{code}}
{
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "birthDate": "",
  "refID": "",
  "signResult": {
    "endUser": "",
    "merchant": "",
    "hash": ""
  }
}

After (V3)​

GET /v3/bankid-no/sign/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
  "id": "",
  "status": "",
  "error": "",
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "birthDate": "",
  "refId": "",
  "signResult": {
    "endUser": "",
    "merchant": "",
    "hash": ""
  }
}

Summary of changes​

  • The path to the endpoint has changed
  • The endpoint is now authenticated using Basic Auth.
  • The redirect request parameter code is renamed to id.
  • The possible values of status has changed, see Collect.
  • refID has been renamed to refId. Note the lowercase 'd'.

Start MitID authentication​

Before (V2)​

POST /v2/{{accountId}}/dk/login
Request body​
{
  "refID": "",
  "referenceText": "",
  "secretKey": ""
}
Response body​
{
  "loginLink": ""
}

After (V3)​

POST /v3/mitid/auth
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
Request body​
{
  "referenceText": "",
  "refId": ""
}
Response body​
{
  "id": "",
  "refId": "",
  "url": ""
}

Summary of changes​

  • The path to the endpoint has changed
  • secretKey has been removed in favor of Basic Auth.
  • loginLink has been renamed to url.
  • refID has been renamed to refId. Note the lowercase 'd'.

Get MitID authentication status​

Before (V2)​

GET /v2/{{accountId}}/dk/verify/{{code}}
{
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "birthDate": "",
  "refID": ""
}

After (V3)​

GET /v3/mitid/auth/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
  "id": "",
  "status": "",
  "error": "",
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "birthDate": "",
  "refId": ""
}

Summary of changes​

  • The path to the endpoint has changed
  • The endpoint is now authenticated using Basic Auth.
  • The possible values of status has changed, see Collect.
  • The birthDate format has changed from dd.MM.yyyy to yyyy-MM-dd.
  • refID has been renamed to refId. Note the lowercase 'd'.

Start MitID signing​

Before (V2)​

POST /v2/{{accountId}}/dk/sign
Request body​
{
  "secretKey": "",
  "signText": "",
  "refID": ""
}
Response body​
{
  "signLink": ""
}

After (V3)​

POST /v3/mitid/sign
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
Request body​
{
  "text": "",
  "refId": ""
}
Response body​
{
  "id": "",
  "refId": "",
  "url": ""
}

Summary of changes​

  • The path to the endpoint has changed
  • secretKey has been removed in favor of Basic Auth.
  • signLink has been renamed to url.
  • signText has been renamed to text.
  • refID has been renamed to refId. Note the lowercase 'd'.

Get MitID signing status​

Before (V2)​

GET /v2/{{accountId}}/dk/verify/{{code}}
{
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "birthDate": "",
  "refID": "",
  "checksum": ""
}

After (V3)​

GET /v3/mitid/sign/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
  "id": "",
  "status": "",
  "error": "",
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "birthDate": "",
  "refId": "",
  "signResult": {
    "checksum": ""
  }
}

Summary of changes​

  • The path to the endpoint has changed
  • The endpoint is now authenticated using Basic Auth.
  • The redirect request parameter code is renamed to id.
  • The possible values of status has changed, see Collect.
  • The birthDate format has changed from dd.MM.yyyy to yyyy-MM-dd.
  • checksum has been wrapped in a signResult object.
  • refID has been renamed to refId. Note the lowercase 'd'.

Start FTN authentication​

Before (V2)​

POST /v2/{{accountId}}/fi/login
Request body​
{
  "refID": "",
  "secretKey": ""
}
Response body​
{
  "loginLink": ""
}

After (V3)​

POST /v3/ftn/auth
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
Request body​
{
  "refId": ""
}
Response body​
{
  "id": "",
  "refId": "",
  "url": ""
}

Summary of changes​

  • The path to the endpoint has changed
  • secretKey has been removed in favor of Basic Auth.
  • loginLink has been renamed to url.
  • refID has been renamed to refId. Note the lowercase 'd'.

Get FTN authentication status​

Before (V2)​

GET /v2/{{accountId}}/fi/verify/{{code}}
{
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "birthDate": "",
  "refID": ""
}

After (V3)​

GET /v3/ftn/auth/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
  "id": "",
  "status": "",
  "error": "",
  "ssn": "",
  "name": "",
  "givenName": "",
  "surname": "",
  "birthDate": "",
  "refId": ""
}

Summary of changes​

  • The path to the endpoint has changed
  • The endpoint is now authenticated using Basic Auth.
  • The possible values of status has changed, see Collect.
  • The birthDate format has changed from dd.MM.yyyy to yyyy-MM-dd.
  • refID has been renamed to refId. Note the lowercase 'd'.