Authentication

Authentication for Banking Services is done using a standard OAuth2 Client Credentials Flow. This flow is a good industry standard for machine-to-machine communication in a secure manner.

For general information about what a Client Credentials Flow is, you can have a look at Auth0’s description of the flow .

A Word of Advice

OAuth2 flows are a very standard way of authenticating to APIs, and as such most languages have libraries to help you handle the tokens in the best possible way. We suggest you use the industry standard tooling for your given language to retrieve and cache tokens. While the client_credentials flow is very simple, it can be easy to get some details wrong when working with OAuth2 flows.

So while the following will show a way to get a token in a very handheld manner, we suggest you use the best possible tooling for the job in your applications.

How do we get Client Credentials?

During the onboarding process with Lunar, you will be given credentials to our OAuth2 API. This will be given to you in a secure manner and will consist of a client_id and a client_secret. Keep the client_secret safe - if you lose it, we will have to generate you a new client.

Note that we can set you up with multiple OAuth2 clients if you so wish. This can make sense in case you want separate services to have separate credentials for our APIs.

How do we use it in practice?

For our environments, the AUTH_BASE_URL and AUDIENCE required to call to get a token for the Lunar APIs are:

The client_credentials TokenURL is:

https://${AUTH_BASE_URL}/oauth2/token

And note that if your library needs our .well-known path, this can be found at:

https://${AUTH_BASE_URL}/.well-known/openid-configuration

A Proof of Concept Call

The short description of the flow is that you are given a client_id and client_secret that you use to get a Access Token by calling a /oauth2/token endpoint. You can then call the Banking Services APIs and authenticate by putting Bearer ${ACCESS_TOKEN} in your Authorization header. So let’s see how to make a proof of concept call to /oauth2/token.

Clients will be set up with the client_secret_basic authorization method, meaning you authenticate with the /oauth2/token endpoint by calculating a base64 blob:

base64(${CLIENT_ID}:${CLIENT_SECRET})

Once you have the blob, you include it in your Authorization header prefixed with Basic.

You will also need to specify parameters for grant_type (client_credentials) and audience (see table above).

The call to /oauth2/token then looks like this:

curl -X POST https://${AUTH_BASE_URL}/oauth2/token \
    -H "Authorization: Basic MjBiMDgwNzktNTZiNi00MmE2LTk5YTItOTJjNzFmYmYxYTBjOkpmQWhpLWZsNFJoaGljRnBWWDdBRzd6THFQ" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" \
    -d "audience=${AUDIENCE}"

The Response

Once you have made a curl call to the endpoint, you get a payload of the form:

{
  "access_token": "${ACCESS_TOKEN}",
  "expires_in": 299,
  "scope": "",
  "token_type": "bearer"
}

You can then use the token to make calls to our Banking Services APIs.

As you may have already noted, the resulting payload states that tokens are valid for five minutes. As such, you should cache tokens to avoid having to create a new token for every API call you make.

Once you have done the proof of concept curl call, it should be a simple matter to implement this in your actual application code, regardless of your chosen language.

Using Your Token For the First Time

If you just want to see what it looks like to use your newly minted token, you can make a call to the /userinfo endpoint, which is a standard endpoint of the protocol:

curl -X GET https://${AUTH_BASE_URL}/userinfo \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

If the call is a success, you should get a response back containing aud (your client_id), the iat (issued at) and the issuer.

Similarly, you can call the connectivity API:

curl -s -v -X GET ${API_BASE_URL}/v1/connectivity/whoami \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"