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:
- Base URL (https://<phenixid_server_domain>:port/)
- tenant id
- tenant password
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(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"
}
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"
}
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"
}
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"
}
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"
}