Using PhenixID HTTP proxy API for Swedish BankID authentication and signing

This article, targeted to application developers, describes how to consume the PhenixID HTTP proxy API for Swedish BankID authentication and signing.

Prerequisites

To start, this information must have been provided to you from the PhenixID server administrator:

Starting an authentication

The request to start an authentication is done using HTTP PUT to the uri "api/authentication/bankid/auth/start".

 

Example shown below where:

Base URL = https://integration.phenixid.se

tenant id = default

tenant password = secret

PUT: api/authentication/bankid/auth/start

HEADERS:
Content-Type:application/json
tenant:default
password:secret
host:integration.phenixid.se

BODY:
{
"endUserIp": "127.0.0.1"
}
Click to copy

Note that the headers in the example are mandatory where tenant and password are variables.

The HTTP body is expected to be json formatted. enduserIp is mandatory. 

In addition "personalNumber" can be added(only bankid v5.1). 

userVisibleData, userVisibleDataFormat and userNonVisibleData

The API supports adding requirement  see BankID documentation.

Starting an signature request

The request to start an authentication is done using HTTP PUT to the uri "/api/authentication/bankid/sign/start". Example shown below.

PUT: /api/authentication/bankid/sign/start

HEADERS:
Content-Type:application/json
tenant:default
password:secret
host:integration.phenixid.se

BODY:
{
"endUserIp": "127.0.0.1",
"userVisibleData":"Gött räksmörgås"
}
Click to copy

Note that the headers in the example are mandatory where tenant and password are variables.

The HTTP body is expected to be json formatted. enduserIp and userVisibleData are mandatory. 

In addition "personalNumber" can be added(only bankid v5.1). 

userVisibleDataFormat and userNonVisibleData

The API supports adding requirement  see BankID documentation.

Starting a phone auth request

The request to start an authentication from a phone service is done using HTTP PUT to the uri "/api/authentication/bankid/phone/auth". Example shown below:

PUT: /api/authentication/bankid/phone/auth

HEADERS:
Content-Type:application/json
tenant:default
password:secret
host:integration.phenixid.se

BODY:
{
"callInitiator" : "user",
"userVisibleData":"Base-64-encoded-string"
}
Click to copy

Starting a phone sign request

The request to start a signing from a phone service is done using HTTP PUT to the uri "/api/authentication/bankid/phone/sign". Example shown below:

PUT: /api/authentication/bankid/phone/sign

HEADERS:
Content-Type:application/json
tenant:default
password:secret
host:integration.phenixid.se

BODY:
{
"callInitiator" : "user",
"userVisibleData":"Base-64-encoded-string"
}
Click to copy

Response from a start auth or start sign

Since the API is pretty much proxying requests to BankID expected responses are documentented in the BankID documentation.

The PAS server have 3 possible response codes:

  • 200 - OK
    The response will contain a json body with the parameters:
    orderRef (Use this value to check the status in subsequest requests)
    autostarttoken
    (if personalNumber was not part of the request) qrStartToken and qrStartSecret
  • 403 - Tenant failure
  • 400 - Parsing failure/missing mandatory data
  • 500 - General server error

Getting status from an order

The request to start an authentication is done using HTTP PUT to "/api/authentication/bankid/collect". Example shown below.

PUT: /api/authentication/bankid/collect

HEADERS:
Content-Type:application/json
tenant:default
password:secret
host:integration.phenixid.se

BODY:
{
"orderRef": "413200b2-976b-4769-8722-7b7dd37411f9"
}
Click to copy

Note that the headers in the example are mandatory where tenant and password are variables.

The HTTP body is expected to be json formatted. orderRef is mandatory. 

Response from a collect call.

Since the API is pretty much proxying requests to BankID expected responses are documented in the BankID documentation.

If the order returns as COMPLETE and the onCompletePipeID is configured, the PIPE id will be executed. The response from the pipe will the n be added to the bankid response and sent to the client.

Data sent to the executing pipe is:

  • personalNumber
  • name
  • givenName
  • surname
  • ipAddress
  • notBefore (not applicable in v6.0 of the bankIdApi)
  • notAfter  (not applicable in v6.0 of the bankIdApi)
  • signature
  • ocspResponse
  • tenant
  • orderRef

New in v6.0 of the BankID api:

  • uhi 
  • bankIdIssueDate 

Cancelling an order

To cancel a pending order send call to /api/authentication/bankid/cancel

Example

PUT: /api/authentication/bankid/cancel

HEADERS:
Content-Type:application/json
tenant:default
password:secret
host:integration.phenixid.se

BODY:
{
"orderRef": "413200b2-976b-4769-8722-7b7dd37411f9"
}
Click to copy