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 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>”}