Using PhenixID HTTP API for Swedish BankID authentication

Overview

To use the API, two methods must be called. The first API method call is to trigger the authentication. This will return a transaction ID value. The second API method call will poll the status of the authentication. The API client must poll until a status=OK or an error is returned.

Prerequisites

- PhenixID Authentication Services HTTP API configured

- BankID client

- BankID enrolled

- If PhenixID Authentication Services HTTP API is protected with client certificate authentication: Client certificate (p12)

- If PhenixID Authentication Services HTTP API is protected with basic authentication: Username and password

Trigger authentication - data to be fetched before api call

To trigger bankid authentication in v5.1 of the BankID api, the api client may fetch this value:

- Personal identification number (personnummer)

 With v6.0 of the BankID api autostart or start with Qr-code is mandatory.

For information how to use autostart and Qr-Code for bankid, please view the relying party guidelines here.

Trigger authentication - api call

Request

Method: HTTP PUT

Endpoint: /api/authentication/bankid_start_auth

Headers:

Name Value
 Mandatory Comment
Content-Type application/json Yes
tenant t1 Yes .Value must be given to you by PhenixID Authentication Services admin, it might differ depending on the environment.
Authorization <basic_auth_value> No If applicable, username and password must be given to you by PhenixID Authentication Services admin.

The body of the request can be left empty. Configure your BankIDAuthenticateValve with the attributes to be handled in the request.

Body:

{
"userVisibleData":"text to be shown"
}

Json structure properties:

Name Value Mandatory Comment
pnr <user personal identification number> No Only accepted in v5.1 of the BankID API
Personal identification number. 12 digits.
Numbers only.
Please view BankID documentation for recommendations regarding autostart flows.




Example request (Please note that authorization data is not included in this example).

 

PUT /api/authentication/bankid_start_auth HTTP/1.1
Host: demo.phenixid.net
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{ "pnr":"191212127771" }

Response

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3900
{
  "transactionID":"829b3b56-5a0a-449f-8dc8-50e6772c076f"
}

Example request autostart (Please note that authorization data is not included in this example).

 

PUT /api/authentication/bankid_start_auth HTTP/1.1
Host: demo.phenixid.net
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{ }

Example response autostart

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3900
{
 "autostarttoken": "c5698d12-0cf4-4456-ae7b-d795f9967798",    "qrStartSecret": "78ed3fab-020c-41e8-a4ba-b64fb00788e1",    "qrStartToken": "0c32dc95-74a4-4209-9ff2-e819bb740b8a",    "transactionID": "eca638ac-fa8a-4943-bec1-1d83b4c7d3a6"
}

Poll authentication status - use transactionID

The API client must fetch the transactionID returned by the Trigger authentication call.

The API client must call the Poll authentication status API method periodically until it returns a status OK or an error message.

Poll authentication status - api call

Request

Method: HTTP PUT

Endpoint: /api/authentication/bankid_check_auth

Headers:

Name Value Mandatory Comment
Content-Type application/json Yes
tenant t1 Yes This value must be given to you by the PhenixID Authentication Services admin.
Authorization <basic_auth_value> No Basic authentication username and password must be given to you by PhenixID Authentication Services admin.

Body:

The body must contains a json structure. 

{"transactionID":"..."}

Json structure properties:

Name Value Mandatory Comment
transactionID <Value_returned_from_trigger_auth> Yes

Example request (Please note that authorization data is not included in this example).

PUT /api/authentication/bankid_check_auth HTTP/1.1
Host: demo.phenixid.net
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{ "transactionID": "b3734e10-d5e4-49a9-b5fb-affa89e31191" }

Response

Response

The response body JSON structure properties:

 

Name Possible values Comment
status OK
PENDING
USER_SIGN
ERROR
CANCELLED
 PENDING -> User did not yet open the BankID application. Continue to poll.

USER_SIGN -> User opened the BankID application. Continue to poll.

Other status -> Stop polling

Status=OK means successful authentication 
personalNumber
Personal identification number (personnummer) of BankID holder.
name
Full name of BankID holder. Only available if status=OK.
givenName
Given name (first name) of BankID holder. Only available if status=OK.
surName
Last name of BankID holder. Only available if status=OK.
ocspResponse
OCSP response value of the authentication. Only available if status=OK.
signature
Signature value of the authentication. Only available if status=OK.
message
Error message. Only available if status=ERROR.
details
Detailed error message. Only available if status=ERROR.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 390010
{
    "surName": "Landgren",
    "givenName": "Reine",
    "name": "Reine Landgren",
    "personalNumber": "191212127771",
    "status": "OK"
}

Common errors

Common errors from the BankID backend will result in a HTTP Status 200 with a body containing the error message:

{”message”:”<error explained>”}