PhenixID DocumentationPhenixID Authentication ServicesSolutions Developer integration guidesUsing PhenixID HTTP proxy API for Swedish BankID authentication and signing

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

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. 

The API supports adding requirement which is transparent to 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"
}

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 and userNonVisibleData can be added. 

The API supports adding requirement which is transparent to BankID documentation.

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)
  • 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"
}

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 documentented 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
  • notAfter
  • signature
  • signature
  • ocspResponse
  • tenant
  • orderRef

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