Swedish BankID integration for the UI-less backend, suitable for server, mobile, desktop app or custom scenarios.

API Calls

Setup: POST to https://env.zignsec.com/v2/bankidse/method
Result: GET from https://env.zignsec.com/v2/bankidse/collect?orderref=orderRef
Cancel: POST to https://env.zignsec.com/v2/bankidse/cancel

where
env is API or test
method is Authenticate or Sign
orderRef is BankID’s session identifier retrieved on the first call.

Call Sequence

The first call is an initiation of the end user´s intended operation, either Authenticate or Sign. Initiation call will immediately activate the authenticate or sign process on the BankID backend and the BankID app will be notified at once to show either the authenticate or sign page. Consider having a web hook configured for “completed/error” to avoid polling.

Authentication vs Signing

The use case for /authenticate or /sign are almost identical, but sign shows an extra text message in the BankID app, trough the two extra parameters UserVisibleData and UserNonVisibleData.

The BankID Relying Party Guidelines

Have a look at the BankID Relying Party Guidelines for details about the underlying BankID service, such as parameters, return values and error conditions.

Exceptions

The calls to native BankID web service can throw a number of SOAP-Exceptions, where the exception Message string is set to a code that identifies the error situation for the calling party´s understanding, see also BankID Relying Party Guidelines:

  • USER_CANCEL means the user opened and then cancelled the dialog in the BankID app. Shows message:
  • EXPIRED_TRANSACTION means a timeout due to inactivity has been reached – i.e., the user did not locate to his/her phone and start the BankID app within the 3 minutes timeout period.

As the ZignSec integration uses REST and not SOAP API technology, the native BankID API’s SOAP exception needs to be translated into an error code and a description to be stored in the errors array in the returned JSON.

Request Parameters

ParameterDescriptionRequired
PersonalNumberThe ID number of the user trying to be authenticated. If the ID number is omitted the user must use the same device and the client must be started with the autoStartToken returned in orderResponse.No
endUserInfoList of EndUserInfoType: { "type": "", "value": "" } Used to provide information related to the user and the user’s computer/device to the BankID-server.No
userVisibleDataOnly forSign method. The text to be displayed and signed. Must be UTF-8 encoded. The value must be base 64-encoded. 1-40 000 characters (after base 64-encoding). The text can be formatted using CR = new line, LF = new line and CRLF = new lineYes, on Sign
userNonVisibleDataJust for Sign method. Data not displayed to the user. The value must be base 64-encoded. 0 – 200 000 characters (after base 64-encoding).No
lookupPersonAddressCurrently works for Swedish BankID and Swedish Banking API. If set to true will automatically do a Swedish person address lookup from the verified personalNumber using LookupPerson API and the official population register. The call is charged separately, which means that additional charges will be incurred.No
relayStateAdded by ZignSec. This semi-optional parameter will be returned to you at the redirect back to your server. Use it to link an unique ID of your choice that you can parse. If not relayState is specified, ZignSec will automatically set the ZignSec’s unique session identifier, the RequestID token here. Example: relaystate=zignsec_eid_1234No
webhookAdded by ZignSec. A URL where success/error results will automatically be POST:ed. It can be set either here or on the merchant’s setting, see setting eid_webhook at merchant settings page or this general page web hooks for success and error During test you try https://webhook.site/ for free web hook urls. No
requirementNOTE: Include setting AutoStartTokenRequired=Yes to require that login must be performed scanning a QR code. Adding this setting will also include a image URL to the QR Code in the setup Response body. Used by RP to set requirements how the authentication or sign operation must be performed. Default rules are applied if omitted. Example: { “AutoStartTokenRequired”: "Yes" }No
endUserIpThe user IP address as seen by RP. String. IPv4 and IPv6 is allowed. NOTE: the importance of using the correct IP address. It must be the IP address representing the user agent (the end user device) as seen by the RP. If there is a proxy for inbound traffic, special considerations may need to be taken to get the correct address. In some use cases the IP address is not available, for instance for voice based services. In this case, the internal representation of those systems IP address is ok to use.Yes

Examples of setting up a BankID login session

Example 1 – Authenticate

POST https://test.zignsec.com/v2/BankIDSE/Authenticate HTTP/1.1
User-Agent: Fiddler
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Authorization: xxxxxxxx-e2a2-4968-b651-5352305c9fb0

{"PersonalNumber":"191212121212"}

Example 2 – Authenticate with lookupPersonAddress=true

POST https://test.zignsec.com/v2/BankIDSE/Authenticate HTTP/1.1
User-Agent: Fiddler
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Authorization: xxxxxxxx-e2a2-4968-b651-5352305c9fb0

{"PersonalNumber":"191212121212","LookupPersonAddress":true}

Example 3 – Sign

Note that both userVisibleData and userNonVisibleData must be base64-encoded, and that userNonVisibleData is optional and can be left out as in this example.

POST https://test.zignsec.com/v2/BankIDSE/Sign HTTP/1.1
User-Agent: Fiddler
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Authorization: xxxxxxxx-e2a2-4968-b651-5352305c9fb0

{"PersonalNumber":"191212121212", "userVisibleData":"VGVzdGFy"}

Response example 1-3

{
	"id": "d9e7994f-6f1b-43e1-ab46-ec6833ea2202",
	"errors": [],
	"orderRef": "527312bb-8c14-4cea-95a0-d50218ae1d8a",
	"autoStartToken": "09b3822c-2436-40a7-bc50-bdaa82dfae01"
}

Example 4 – Authenticate with AutoStartTokenRequired=Yes

POST https://test.zignsec.com/v2/BankIDSE/Authenticate HTTP/1.1
User-Agent: Fiddler
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Authorization: xxxxxxxx-e2a2-4968-b651-5352305c9fb0

{ "PersonalNumber":"191212121212", "requirement": {"AutoStartTokenRequired": "Yes"} }

Response example 4

{
    "id": "d9e7994f-6f1b-43e1-ab46-ec6833ea2202",
    "errors": [],
    "orderRef": "527312bb-8c14-4cea-95a0-d50218ae1d8a",
    "autoStartToken": "09b3822c-2436-40a7-bc50-bdaa82dfae01",
    "qrCodeLink": "https://test.zignsec.com/v2/qrcode?text=bankid:///?autostarttoken=09b3822c-2436-40a7-bc50-bdaa82dfae01"
}

Step 2. Start the login workflow in a BankID app.

There are two approaches to start BankID app:

  1. To start the BankID app manually, only if PersonalNumber is set
  2. To start the BankID app with autostart URL, required when PersonalNumber is NOT set

The field autoStartToken is used to construct a schema URL registered on the operating system on the form bankid:///?autostarttoken=[TOKEN]&redirect=[RETURNURL]. The autoStartToken URL can be used to automatically start up the BankID app from another app or from the browser. Of course the BankID app needs to be installed on the active device, running Android, IOS or Window. The fields orderRef and autoStartToken originate from the BankID response object (which is of type OrderResponseType), whereas the fields id and and errors are set by ZignSec.

ParameterDescriptionRequired
autoStartTokenHolds the autoStartToken that was returned from the web service call. If the user personal number was not included in the web service call the autoStartToken must be provided. We strongly recommend to always use the autoStartToken when the URL is used to start the client. If it is not included and the user reloads the page or if the page erroneously repeats the start command, the user may get an error claiming that the BankID is missing. The likelihood of this to happen is reduced if autoStartToken is used. Note that the parameter names must be lower case. 
redirectThe BankID app uses the parameter redirect to launch the RP web app after completed (including cancelled) auth or sign. The redirect URL must be UTF-8 and URL encoded and should match the web address the user is visiting when RP web app launches the BankID app. It may include parameters to be passed to the browser. For iOS the redirect must have a value. For all other platforms it may be empty (“redirect=”), or set to “null” (“redirect=null”). If it is empty or null the BankID app will terminate without launching any URL and the calling application will be in focus. The general recommendation is to use redirect=null when it is possible. Note for Windows and macOS If redirect has a value the redirect parameter must be used together with autoStartToken. If autoStartToken is excluded, the content of redirect will be ignored and the behavior will be as if redirect=null. Note for Android If the user has several browsers installed on an Android device the user is sometimes presented with a question asking what browser to use. BankID recommends that redirect=null is used on Android. This ensures the user will return to the browser previously used.Required

Step 3. Get status/results

Alt 1: Let a webhook receive results, progressStatus or errors

To set up a webhook URL for callback, contact ZignSec. Results will be POST:ed to the URL, see this example.

Alt 2: Call API to retrieve final results, progressStatus or errors

GET from https://env.zignsec.com/v2/bankidse//collect?orderref=orderRef where env is API or test orderRef is BankID’s orderRef in the response from step 1.

Polling Interval

The guidelines recommend polling for results every 2 seconds.

Fetching Final Result Multiple Times

We follow the BankID backend behavior and allow only one call for final result, whether finished with error or finished with success progressStatus=COMPLETE. The final result cannot be collected twice and the second call will receive an error with code=INVALID_PARAMETERS.

Get Results – Request example

orderRef was taken from the response of a previous Authenticate or Sign initiation call.
GET https://test.zignsec.com/v2/BankIDSE/Collect?orderRef=8e4dd041-e38f-463b-b286-a6c5e35d462d HTTP/1.1
User-Agent: Fiddler
Host: test.zignsec.com 
Authorization: xxxxxxxx-e2a2-4968-b651-5352305c

Example response

The final success response from calling Collect (after having completed a signing process in the BankID app). personalNumber, givenName, surname and name are the person-identity data items. signature is a base64-encoded xmldsig-document that can be used to verify the operation’s PKI signature in retrospect and ocspResponse is used to describe and verify the validity of the certificate used in the operation. ipAddress is the internet address of the BankID app client as the BankID server discovers it.

{
  "id":"6e8020b9-2458-44e3-b5ac-8dbf41f55bab",
  "errors":[],
  "progressStatus":"COMPLETE",
  "signature":"...   ...",
  "ocspResponse":"...  ...",
  "userInfo":{
    "personalNumber":"191212121212",
    "givenName":"LARS",
    "surname":"SVENSON",
    "name":"LARS SVENSON",
    "notBefore":"2015-11-30T00:00:00+01:00",
    "notAfter":"2017-11-29T23:59:59+01:00",
    "ipAddress":"233.243.246.194"
   },
   "relayState": "abcdefg123456"
}

Example response where lookupPersonAddress=true

{
  "id": "737361a9-044a-4688-877f-c7d599266976",
  "errors": [
    
  ],
  "progressStatus": "COMPLETE",
  "userInfo": {
    "personalNumber": "198710260070",
    "givenName": "JAN ERIK GREN",
    "surname": "GREN",
    "name": "JAN ERIK",
    "notBefore": "2018-10-04T00:00:00+02:00",
    "notAfter": "2020-10-03T23:59:59+02:00",
    "ipAddress": "185.176.146.178"
  },
  "signature": "too long to display",
  "ocspResponse": "too long to display...",
  "LookupPersonAddress": {
    "PersonStatus": "",
    "FirstName": "Jan Erik",
    "LastName": "Gren",
    "MainFirstName": "Jan",
    "Address": "Tranebergv 3",
    "Address2": null,
    "PostalCode": "12345",
    "Location": null,
    "City": "Solna",
    "Province": null,
    "CountryCode": "se",
    "Phone": null,
    "PhoneNumbers": [
      "08-51234567",
      "073-41234567"
    ],
    "Email": null,
    "DateOfBirth": "19871126",
    "BirthYear": 1987,
    "BirthMonth": 11,
    "BirthDayOfMonth": 26,
    "Age": 30,
    "PersonalNumber": "198711260070",
    "_DataSource": "DP05"
  },
  "relayState": "abcdefg123456"
}

ProgressStatus values (from official guidelines)

StatusReasonAction by RP
OUTSTANDING_TRANSACTIONThe order is being processed. The client has not yet received the order. The status will later change to NO_CLIENT, STARTED or USER_SIGN.If RP tried to start the client automatically, the RP should inform the user that the app is starting. Message RFA13 should be used. If RP did not try to start the client automatically, the RP should inform the user that she needs to start the app. Message RFA1 should be used.
NO_CLIENT The order is being processed. The client has not yet received the order. If the user did not provide her ID number the error START_FAILED will be returned in this situation.If RP tried to start the client automatically: This status indicates that the start failed or the users BankID was not available in the started client. RP should inform the user. Message RFA1 should be used. If RP did not try to start the client automatically: This status indicates that the user not yet has started her client. RP should inform the user. Message RFA1 should be used.
STARTEDA client has been started with the autoStartToken but a usable ID has not yet been found in the started client. When the client starts there may be a short delay until all ID:s are registered. The user may not have any usable ID:s at all, or has not yet inserted their smart card.If RP does not require the autoStartToken to be used and the user provided her ID number the RP should inform the user of possible solutions. Message RFA14 should be used. If RP require the autoStartToken to be used or the user did not provide her ID number the RP should inform the user of possible solutions. Message RFA15 should be used. Note: STARTED is not an error, RP should keep on polling using collect.
USER_SIGNThe client has received the order.The RP should inform the user. Message RFA9 should be used.
USER_REQNot used 
COMPLETEThe user has provided the security code and completed the order. Collect response includes the signature, user information and the ocsp response.RP should control the user information returned in userInfo and continue their process

Recommended user messages (from official guidelines)

Short NameEnglish TextSwedish TextEvent or API Code Mapping
RFA1Start your BankID appStarta BankID-appenOUTSTANDING_ TRANSACTION, NO_CLIENT
RFA2The BankID app is not installed. Please contact your internet bank.Du har inte BankID-appen installerad. Kontakta din internetbank.The BankID app is not installed in the mobile device.
RFA3Action cancelled. Please try again.Åtgärden avbruten. Försök igenCANCELLED
RFA4An identification or signing for this personal number is already started. Please try againEn identifiering eller underskrift för det här personnumret är redan påbörjad. Försök igen.ALREADY IN PROGRESS
RFA5Internal error. Please try again.Internt tekniskt fel. Försök igenRETRY, INTERNAL_ERROR
RFA6Action cancelled. Åtgärden avbruten.USER_CANCEL
RFA8The BankID app is not responding. Please check that the program is started and that you have internet access. If you don’t have a valid BankID you can get one from your bank. Try again.BankID-appen svarar inte. Kontrollera att den är startad och att du har internetanslutning. Om du inte har något giltigt BankID kan du hämta ett hos din Bank. Försök sedan igen.EXPIRED_TRANSACTION
RFA9Enter your security code in the BankID app and select Identify or Sign.Skriv in din säkerhetskod i BankIDappen och välj Legitimera eller Skriv under.USER_SIGN

Deprecated

RFA12

 Deprecated

Internal error. Update your BankID app and try again.

Deprecated

Internt tekniskt fel. Uppdatera BankID-appen och försök igen.

CLIENT_ERR

RFA13Trying to start your BankID app.Försöker starta BankID-appen.OUTSTANDING_ TRANSACTION
RFA14 (A)Searching for BankID:s, it may take a little while… If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this login/signature on this computer. If you have a BankID card, please insert it into your card reader. If you don’t have a BankID you can order one from your internet bank. If you have a BankID on another device you can start the BankID app on that device.Söker efter BankID, det kan ta en liten stund… Om det har gått några sekunder och inget BankID har hittats har du sannolikt inget BankID som går att använda för den aktuella inloggningen/underskriften i den här datorn. Om du har ett BankIDkort, sätt in det i kortläsaren. Om du inte har något BankID kan du hämta ett hos din internetbank. Om du har ett BankID på en annan enhet kan du starta din BankID-app där.STARTED – The RP provided the ID number in the web service call (without using AutoStartToken required). The user accesses the service using a personal computer
RFA14 (B)Searching for BankID:s, it may take a little while… If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this login/signature on this device. If you don’t have a BankID you can order one from your internet bank. If you have a BankID on another device you can start the BankID app on that device.Söker efter BankID, det kan ta en liten stund… Om det har gått några sekunder och inget BankID har hittats har du sannolikt inget BankID som går att använda för den aktuella inloggningen/underskriften i den här enheten. Om du inte har något BankID kan du hämta ett hos din internetbank. Om du har ett BankID på en annan enhet kan du starta din BankID-app där.STARTED – The RP provided the ID number in the web service call (without using AutoStartToken required). The user accesses the service using a mobile device.
RFA15 (A)Searching for BankID:s, it may take a little while… If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this login/signature on this computer. If you have a BankID card, please insert it into your card reader. If you don’t have a BankID you can order one from your internet bank.Söker efter BankID, det kan ta en liten stund… Om det har gått några sekunder och inget BankID har hittats har du sannolikt inget BankID som går att använda för den aktuella inloggningen/underskriften i den här datorn. Om du har ett BankIDkort, sätt in det i kortläsaren. Om du inte har något BankID kan du hämta ett hos din internetbank.STARTED – The RP did not provide the ID number in the web service call. The user accesses the service using a personal computer.
RFA15 (B)Searching for BankID:s, it may take a little while… If a few seconds have passed and still no BankID has been found, you probably don’t have a BankID which can be used for this login/signature on this device. If you don’t have a BankID you can order one from your internet bankSöker efter BankID, det kan ta en liten stund… Om det har gått några sekunder och inget BankID har hittats har du sannolikt inget BankID som går att använda för den aktuella inloggningen/underskriften i den här enheten. Om du inte har något BankID kan du hämta ett hos din internetbank.STARTED – The RP did not provide the ID number in the web service call. The user accesses the service using a mobile device.
RFA16The BankID you are trying to use is revoked or too old. Please use another BankID or order a new one from your internet bank.Det BankID du försöker använda är för gammalt eller spärrat. Använd ett annat BankID eller hämta ett nytt hos din internetbank.CERTIFICATE_E RR
RFA17The BankID app couldn’t be found on your computer or mobile device. Please install it and order a BankID from your internet bank. Install the app from install.bankid.com.BankID-appen verkar inte finnas i din dator eller telefon. Installera den och hämta ett BankID hos din internetbank. Installera appen från install.bankid.com.START_FAILED
RFA18Start the BankID appStarta BankID-appenThe name of link or button used to start the BankID App
RFA19Would you like to login or sign with a BankID on this computer or with a Mobile BankID?Vill du logga in eller skriva under med BankID på den här datorn eller med ett Mobilt BankID?The user access the service using a browser on a personal computer.
RFA20Would you like to login or sign with a BankID on this device or with a BankID on another device?Vill du logga in eller skriva under med ett BankID på den här enheten eller med ett BankID på en annan enhet?The user access the service using a browser on a mobile device.
RFA22Unknown error. Please try again.Okänt fel. Försök igen.An error occurred. The errorCode is unknown to ZignSec.

Error codes for Auth/Sign (from official guidelines)

CodeReasonAction by RP
INVALID_PARAMETERSInvalid parameter. Invalid use of methodRP must not try the same request again. This is an internal error within RP’s system and must not be communicated to the user as a BankID error.
ALREADY_IN_PROGRESSAn order for this user is already in progress. The order is aborted. No order is createdRP must inform the user that a login or signing operation is already initiated for this user. Message RFA4 should be used.
INTERNAL_ERRORInternal technical error in the BankID system.RP must not automatically try again. RP must inform the user that a technical error has occurred. Message RFA5 should be used.
RETRYInternal technical error in the BankID system.RP must not automatically try again. RP must inform the user that a technical error has occurred. Message RFA5 should be used.
ACCESS_DENIED_RPRP does not have access to the service or requested operation.RP must not try the same request again. This is an internal error within RP’s system and must not be communicated to the user as a BankID error.

Error codes for Collect

Relates to BankID official guidelines
NOTE: With ZignSec it is allowed to collect the same order twice within a configurable time span. In underlying BankID implementation multiple collects are not allowed, and you will receive a INVALID_PARAMETERS error after the first collect that was status COMPLETE.

Error codeReasonAction by RP
INVALID_PARAMETERSInvalid parameter. Invalid use of method.RP must not try the same request again. This is an internal error within RP’s system and must not be communicated to the user as a BankID-error.
REQ_PRECONDNot used. 
REQ_ERRORNot used. 
REQ_BLOCKEDNot used. 
INTERNAL_ERRORInternal technical error in the BankID system.RP must not automatically try again. RP must inform the user. Message RFA5.
RETRYInternal technical error in the BankID system.RP must not automatically try again. RP must inform the user. Message RFA5.
ACCESS_DENIED_RPRP does not have access to the service, requested operation or the orderRef.RP must not try the same request again. This is an internal error within RP’s system and must not be communicated to the user as a BankID-error.
CLIENT_ERRInternal technical error. It was not possible to create or verify the transaction.RP must not automatically try again. RP must inform the user. Message RFA12.
EXPIRED_TRANSACTIONThe order has expired. The BankID security app/program did not start, the user did not finalize the signing or the RP called collect too late.RP must inform the user. Message RFA8.
CERTIFICATE_ERRThis error is returned if: 1) The user has entered wrong security code too many times in her mobile device. The Mobile BankID cannot be used. 2) The users BankID is revoked. 3) The users BankID is invalid.RP must inform the user. Message RFA16.
USER_CANCELThe user decided to cancel the order.RP must inform the user. Message RFA6
CANCELLEDThe order was cancelled. The system received a new order for the user.RP must inform the user. Message RFA3.
START_FAILEDThe user did not provide her ID, or the RP requires autoStartToken to be used, but the client did not start within a certain time limit. The reason may be:: 1) RP did not use autoStartToken when starting BankID security program/app. 2) The client software was not installed or other problem with the user’s computer.1) The RP must use autoStartToken when starting the client. 2) The RP must inform the user. Message RFA17.
ALREADY_COLLECTEDNot used. 

 

Cancel a BankID login session 

Cancel – Request example

POST https://test.zignsec.com/v2/BankIDSE/cancel HTTP/1.1
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Authorization: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx9fb0

{
    "orderRef": "527312bb-8c14-4cea-95a0-d50218ae1d8a"
}

Cancel – Response example

{
  "id": "76f2cc59-5e01-40e4-88f5-02eaae62b835",
  "errors": []
}