Authentication

To connect to our APIs you need api credentials in the form of a client_id and client_secret. We will also soon support the use of eIDAS certificates as credentials. If you have not been granted access yet, please visit getting started.

We make use of OAuth2 for authorization with Auth0 as the IDP(Identity Provider) and the client credentials flow. This also means that our API’s only support machine identities and not “person based” access tokens.

How it works

  1. The client requests an access token from https://[environment].eu.auth0.com/oauth/token with client_id and client_secret
  2. The client includes the access_token in the Authorization header in each API request
  3. When the token expires, a new one can be requested using the client credentials

Example in bash(with jq)

# Get access token
curl --request POST \
  --url https://[environment].eu.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":[client_id],"client_secret":[client_secret],"audience":"https://openbanking.[environment].no","grant_type":"client_credentials"}' | jq ".access_token" -r

# Do request
curl --url https://account.[environment].no/v1/accounts \
  --header 'content-type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer $access_token' \
  --header 'PSU-ID: [SSN]' | jq

The example above also contains the header parameter PSU-ID. This parameter is explained in detail in the authorization page.

Visual description of flow

     +-------------+                  +-------------+
     |             |                  |             |
     |             +---authenticate-->+             |
     |   client    |                  |     IDP     |
     |             +<---access_token--+             |
     |             |                  |             |
     +------+------+                  +------+------+
            |                                ^
            |                                |
 request w. |                                |  validate
access_token|       +-------------+          |access_token
            |       |             |          |
            |       |             |          |
            +------>+     API     +----------+
                    |             |
                    |             |
                    +-------------+

Authentication when using our PSD2 fallback mechanism

Under PSD2, banks are required to put in place a “fallback mechanism” for the case when PSD2 APIs are not available. The fallback mechanism is for third parties to write software that uses the traditional online banking interface. Still, Third Party Providers (TPPs) must authenticate themselves before accessing the Payment Service User’s (PSUs) online banking data. There is no “natural” approach to this in traditional user centric online banking websites, so a more untraditional authentication approach needs to be taken for the fallback mechanism.

Requirements for TPPs using Sparebanken Vest’s (SPVs) fallback mechanism

For every HTTP request made to SPV, the following two request headers must be included:

SPV-PSD2-Fallback-TPP-Cert: Base64 encoded JWK Qseal certificate

The TPPs Qseal certificate (including intermediates) must be presented in the JSON Web Key (JWK) format, using the “x5c” (X.509 Certificate Chain) Parameter (see RFC 7517, Section 4.7). The JWK should be UTF-8 encoded and then Base64 encoded for inclusion in the HTTP header.

SPV-PSD2-Fallback-TPP-Qseal: TPP issued JWT

To prove possession of the Qseal certificate private key, a JSON Web Token (JWT) must be constructed. It must be signed with the Qseal private key, using one of the following algorithms (see RFC 7518, Section 3.1):

  • RS256 (RSASSA-PKCS1-v1_5 using SHA-256)
  • ES256 (ECDSA using P-256 and SHA-256)

The JWT must include the following header fields (kid/x5t are example values only):

{
  "alg": "RS256",
  "kid": "E7B3AE9190916FDB58091EEE5FA7A55B56A736B3",
  "x5t": "57OukZCRb9tYCR7uX6elW1anNrM",
  "typ": "JWT"
}

The JWT must include the following claims:

  • “iss”: The full name of the TPP, as registered in the Qseal certificate.
  • “aud”: spv fallback prod for production use
  • “exp”: Expiry must be set to no longer than one hour from the time the token was issued. (A new token should be created after one hour, if needed).
  • “nbf”: Not before, should be set to the time of issuance.
  • “iat”: Issued at, should be set to the time of issuance.
  • “jti”: JWT ID - a 128-bit randomly generated ID.

Inclusion of both headers enables us to verify that the TPP has a valid Qseal certificate and also controls its private key.