We follow the standard Authorization Code grant flow from OAuth2 to authenticate a TPP acting on behalf of a PSU.

As an example, in production our URLs are:

We strongly recommend that you send your requests to these endpoints using application/json or application/x-www-form-urlencoded as content type since query params are considered unsafe.

The access_token has a TTL of 2 hours and the refresh_token has a TTL of 2 weeks.

HTTP Signature

Requests must be signed by TPPs using the private key associated to the certificate provided during the onboarding process.

We follow the draft-cavage-http-signatures-12 to authenticate a TPP.

They keyId shall be formatted as follows: keyId="SN=XXX,CA=YYYYYYYYYYYYYYYY", where XXX is the serial number of the certificate in hexadecimal coding and YYYYYYYYYYYYYYYY is the full Distinguished Name of the Certification Authority encoded following RFC1779.

Here is an exhaustive list of headers that must be signed:

  • (request-target) (mandatory)
  • authorization (mandatory)
  • date (mandatory)
  • digest (only if the request has a body)
  • host (mandatory)
  • psu-corporate-id (only if included in the request)
  • psu-id (only if included in the request)
  • tpp-redirect-uri (only if included in the request)
  • x-request-id (only if included in the request)