Authenticating with OAuth

OAuth is a standard authentication method used to secure APIs and other infrastructure using Public and Private secrets combined with short lived access tokens. Lean's implementation of OAuth is standardised to the specification, so if you have worked with other OAuth providers such as Google, Auth0 or any other number of identity providers you may be familiar with the mechanisms and terms for obtaining and utilising and access token with our APIs.

In order to get started with OAuth authentication you will need the following:

• An Application Dashboard account with Admin or Developer role access.
• Your Application ID and Client Secret (found under the 'Integration' tab in the Application Dashboard).
• An application with access to OAuth as an authentication method.

Scopes & The OAuth flow

OAuth is implemented to secure two channels of access to Lean. Access from your backend to Lean's APIs with scope=api, and access for your customers to the LinkSDK with scope=customer.<customer_id>.

In both cases the flow for creating, editing or modifying resources on the Lean platform is the same.

1. Generate an access token for the request, this will return a JSON Web Bearer Token (JWT)
2. Use the JWT as a Bearer token in subsequent API calls, or as an authentication for the LinkSDK method call you want to make
3. Tokens must be generated in your backend to avoid using the client secret in your frontend since it's vulnerable

Generating Access Tokens for Backend API Calls

curl -X POST 'https://auth.leantech.me/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<LEAN_APPLICATION_ID>' \
--data-urlencode 'client_secret=<LEAN_CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=api'

Generating Access Tokens for SDK Calls

curl -X POST 'https://auth.leantech.me/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<LEAN_APPLICATION_ID>' \
--data-urlencode 'client_secret=<LEAN_CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=customer.<customer_id>'

❗️

Protect your Lean Client Secret

The Client Secret must be managed securely during its entire lifecycle:

• Store the Client Secret in a secure vault or a key-management-system with role based access control, audit and authentication in place
• In case of any secret leakage, revoke your access by generating a new secret in your developer portal account
• Do not share your credentials with anyone
• All token generations MUST be done on the backend and not the frontend. For the SDK token, please generate the JWT token on the backend and pass it to your frontend

📘

In sandbox the url is https://auth.sandbox.leantech.me

Response

{
	"access_token": "YOUR_ENCODED_JWT",
	"token_type": "bearer",
	"expires_in": 3599,
	"scope": "api",
}

Efficient Access Management

For your API scoped Access Token, you may want to store and refresh this as a regular job in your platform, rather than regenerating whenever it's required.

Making an OAuth call to a Lean API

📘

All calls using OAuth should be made using https://api2.leantech.me - this will be deprecated in line with MTLS in a future update

Once you have an access token, this should be included in your API calls. We have used an example of creating a Customer in the sample below.

curl -X POST 'https://api2.leantech.me/customers/v1' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer YOUR_JWT'
--data-raw '{
  "app_user_id": "001"
}'

Using OAuth with the LinkSDK

When starting a new session in the LinkSDK a Customer JWT also needs to be generated in order to validate the session and ensure a secure connection with your customer in your application and Lean.

SDK method calls without OAuth will fail if OAuth is enabled in your application.

Lean.Connect({
  app_token: "YOUR_APP_TOKEN",
  access_token: "YOUR_JWT",
  customer_id: "CUSTOMER_ID",
  permissions: ["accounts, payments"],
  bank_identifier: "ENBD_UAE"
})