Older versionVersion 2.5Developer integration guidesUsing PhenixID HTTP API for BankID authentication

Using PhenixID HTTP API for 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, the api client may fetch this value:

- Personal identification number (personnummer)

 

To trigger bankid authentication with autostart, no data needs to be fetched.

For information how to use autostart 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 Signing Service 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 Signing Service admin.

Body:

The body must contains a json structure.

{
"pnr":"..",
} 

Json structure properties:

Name Value Mandatory Comment
pnr <user personal identification number> No Personal identification number. 12 digits. Numbers only.

If not passed, autostarttoken will be returned. 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" : "c3bf44bd-7700-4c89-a771-e362a59ceaee",
  "transactionID" : "974c6ae0-b24c-42d6-83a1-d575d825d132"
}

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 Signing Service admin.
Authorization <basic_auth_value> No Basic authentication username and password must be given to you by PhenixID Signing Service admin.

Body:

The body must contains a json structure.

{"transactionID":"..."} 

Json structure properties:

Name Value Mandatory Comment
transactionID <Value_returned_from_trigger_sign> 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
ERROR
CANCELLED
PENDING -> 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.
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 will result in a HTTP Status 500 with a body containing the error message:

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