Integrating BankID via IDkollen

This article shows how to verify a person's identity with BankID through IDkollen's API from a Bosbec workflow, using a phone authentication where a member of staff starts the verification on the customer's behalf. It covers the whole flow: storing your IDkollen credentials, starting a session, and reading the result.

Because the verification runs on your own IDkollen certificate, the BankID screen shows your company as the requesting party.

How a verification runs

Every BankID verification follows the same three steps, whatever starts it:

A session is started. Your workflow calls IDkollen with the personal number of the person to be verified, and gets a session id back.
The person approves in the BankID app. This happens on their own device, outside Bosbec — there is nothing to build for this step.
The result comes back. Either you ask IDkollen for it, or IDkollen tells you.

What differs between integrations is who starts the session and how the result reaches you. Both choices are covered below.

Phone authentication, and where it fits

IDkollen calls it a phone authentication when somebody other than the person being verified starts the session. A nurse booking an appointment, for example, needs to confirm who they are speaking to. The nurse enters the customer's personal number, and the customer only has to open their BankID app — the session is already waiting for them.

Two things follow from that:

The party starting the session supplies the personal number, so it has to be known before the workflow runs.
BankID shows the customer an extra notice, confirming that they have chosen to verify this way. That comes from BankID itself, not from IDkollen or Bosbec, and it is expected.

The alternative is a standard authentication, where the person enters their own personal number, typically on a web page. It uses a different endpoint, noted below; everything else in this article is the same.

Before you start

You need an IDkollen account and a Bosbec account. From IDkollen, take two values:

Value	Where it goes in Bosbec
Account ID	An account setting, `idkollen_account_id`
Secret key	A secret, `idkollen_secret`

IDkollen has two environments. Point your requests at https://stgapi.idkollen.se while you are building, and at https://api.idkollen.se once you go live.

Getting the example workflow

The workflow this article describes is ready to import. Open Workflow Builder and navigate to View > Workflow Library. Under Templates, search for IDkollen and you will find "IDkollen: BankId Phone Auth" — select use this template.

Importing it first is worth doing even if you intend to build your own. The sections below describe the jobs it contains, so you can follow along in the workflow rather than reading about it, and the two credentials are the only things you have to fill in before it runs.

Storing your IDkollen credentials

In the Bosbec admin panel, go to Settings at the top right and select Account Settings.
Under Account, add the account ID as idkollen_account_id.
Add the secret key as a secret named idkollen_secret.

Keeping the secret as a secret rather than a plain account setting means it is stored encrypted and never shown back to you. Both are then easy to replace without touching the workflow, which matters when a key is rotated.

Building the Basic Auth header

Every IDkollen endpoint uses Basic authentication: the username is your account ID and the password is your secret key. Basic authentication wants those Base64-encoded as a single id:secret string, so build that once at the start of the workflow and reuse it.

Use a Data operations job with a Base64 operation:

Field	Value
Source	`{{settings.customsettings.idkollen_account_id}}:{{settings.secrets.idkollen_secret}}`
Destination	`metadata.basic_auth_header`
Data type	Text

Writing the result to metadata keeps it available to every later job in the workflow, so the encoding happens once rather than in front of each call. See Workflow Builder expression syntax for how these expressions are written.

The Data operations job Base64-encoding the account ID and secret into metadata, and the Send HTTP request job using the result in an authorization header

Each request then carries the header:

Key	Value
`authorization`	`Basic {{metadata.basic_auth_header}}`

Starting the authentication session

Set up an HTTP channel and create an HTTP trigger on it. This is what the interface or automated process calls to start a verification. See Triggers if these are new to you, and Channels – Incoming for how the channel itself is configured.
Use a JSON pipeline job to assemble the request body. It needs the customer's personal number in ssn, and callInitiator set to RP because the relying party — not the customer — is starting the session.
Use a Send HTTP request job to POST that body to /v3/bankid-se/phone/auth, with the authorization header above and the request body content set to the JSON pipeline's output. See Send HTTP request for the job's other settings.

For a standard authentication, where the person enters their own personal number, post to /v3/bankid-se/auth instead and leave out callInitiator.

In the example workflow the personal number is hardcoded in the JSON pipeline, so you can see the shape the body takes. In a real integration it arrives with the request that fires the trigger.

A successful start returns 201 and an id. That id is the session, and it is what you use to ask about progress.

Getting the result: polling or callback

There are two ways to find out how the verification went.

Approach	Why choose it	What it costs
Polling	Nothing to configure beyond what you already have	You decide how often to ask, so the result arrives slightly later
Callback	Fastest result, and no repeated requests	IDkollen has to approve your callback URL first

The example polls, because that works on any account with no setup.

Polling

GET /v3/bankid-se/auth/{id} with the id you were given. Note the path: status is read from the standard auth endpoint, not from phone/auth.

Put a delay between attempts. IDkollen rate limits this endpoint to one request per second, and there is no benefit to asking faster anyway — a person needs a few seconds to reach for their phone. The example waits three seconds.

Also add a counter limiting how many times the workflow will ask. Without one, anything unexpected leaves a workflow polling indefinitely.

Callback

If you would rather be told than ask, give IDkollen a callbackUrl when you start the session, pointing at a second HTTP trigger on its own path. IDkollen has to approve that URL before it will use it.

With a callback you need a way to match an incoming result back to the session that produced it. Two options, and they are not exclusive:

Send your own reference as refId when you start the session. It comes back untouched in the result, so it is enough on its own to tell one verification from another.
Create a unit for the session with a Unit Pipeline job, storing the session id on it, and look the unit up when the callback arrives. This does more than correlate: it gives the verification somewhere to live, so you can follow it from start to finish and keep the outcome against the person it belongs to.

Handling the three statuses

A status response comes back as one of three values:

PENDING — the customer has not finished yet. Wait, then ask again, until the counter runs out.
FAILED — the verification did not complete. Route this somewhere useful, such as notifying whoever started the session, so they know to try again rather than waiting.
COMPLETED — the verification succeeded, and the response carries the verified person's details. See below.

Treating FAILED as its own route rather than as "not yet successful" is worth the small amount of extra work. It is the difference between the nurse in the example being told something went wrong and simply watching nothing happen.

What a completed verification returns

{
  "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..."
}

Field	What it is
`id`	The session, the same id you polled with
`refId`	The `refId` you sent when starting the session, if any
`ssn`	The personal number of the authenticated person
`name`	Their full name, with `givenName` and `surname` as its parts
`certStartDate`	The date their BankID was issued
`companySignatoryText`	Text describing whether they are a signatory for the organisation number given at the start

Which field matters most depends on how the session started. In a phone authentication you supplied the ssn yourself, so what you learn is the name — confirmation that the number belongs to the person you are speaking to. In a standard authentication the person entered their own number, so ssn is the part you did not already know.

certStartDate is worth knowing about even if you ignore it. A BankID issued very recently is a signal some organisations weigh in fraud checks, since taking over someone's identity usually means issuing a new one.

Use a Parse JSON to resource job to read the response — job_3 in the example workflow — and the fields are then available to everything downstream.

Bear in mind that the response contains a personal number. Avoid writing the whole payload into a log or a message where only the name is needed.

After a successful verification

The example workflow stops once it has a result. What you do with that result is the part specific to your process, and there are a few common directions:

Answer the API call that started the flow, so the calling interface can act on it. See HTTP-in status codes and responses.
Send the outcome as a message to the person who started the session.
Store it against a unit, so the verification is recorded against the person it belongs to.

If a verification does not behave as you expect, Troubleshooting your workflow covers how to follow a run through the workflow log.

Integrating BankID via Bosbec takes the wider view. It compares web and phone flows, goes further into who supplies the personal number and why, and covers Bosbec's own built-in BankID service — which uses Bosbec's certificate rather than yours. Read it if you want the general picture rather than the IDkollen route.

Summary

Store the account ID as an account setting and the secret key as a secret, then Base64-encode them into metadata once and reuse the header for every call.
Start a phone authentication with POST /v3/bankid-se/phone/auth, sending ssn and callInitiator: RP. Use /v3/bankid-se/auth when the person enters their own number.
Read the outcome with GET /v3/bankid-se/auth/{id}, at most once per second, with a retry limit so the workflow always ends.
A completed result gives you the person's name as well as the ssn — in a phone authentication the name is the part you did not already have.
Prefer a callback if IDkollen can approve your URL, and send a refId so you can match the result back to the session.
Give FAILED its own route. Silence is a worse answer than an error.