Authentication

Authenticate your backend requests and Link SDK sessions using OAuth access tokens.

Your backend exchanges your application credentials for a token with the scope required for the operation. Generate all tokens on your backend so your client secret stays secure.

Before you start

You need:

  • A Lean application with OAuth enabled.
  • Your Application ID and client secret from the Lean Dashboard.
  • Access to your backend's secure configuration or secrets manager.

The examples below use the UAE Sandbox.

Understand your credentials

Find your Application ID and client secret in the Lean Dashboard, under Development → Integration settings.

Your Application ID and app token are the same value. Use it as client_id when requesting an OAuth token and as app_token when configuring the Link SDK.

Access tokens are generated through the authentication flow described below.

CredentialWhere to find itHow to use it
Application ID (client_id)Lean Dashboard → Development → Integration settings.Identifies your application in backend token requests.
Client secret (client_secret)Lean Dashboard → Development → Integration settings.Authenticates your application in token requests. Keep it on your backend only.
App token (app_token)The same value as your Application ID.Identifies your application in the Link SDK configuration.
Access token (access_token)Returned by the OAuth token endpoint.Authorises backend API requests or customer SDK sessions, depending on its scope.

Your webhook secret is a separate credential used to verify incoming webhooks. Do not use it as your OAuth client secret.

Choose the token scope

ScopeUse it forToken handling
apiRequests from your backend to Lean's APIs.Keep the token on your backend.
customer.<customer_id>Link SDK sessions for a specific Lean Customer.Generate the token on your backend, then pass it to that customer's frontend session.

Use Lean's customer_id in the customer scope. Your own user reference, app_user_id, is used to associate your user with their Lean Customer.

An OAuth token authorises access to Lean. The customer still needs to complete any bank authentication or consent required by the product flow.

1. Generate a backend token

Send a form-encoded request to the token endpoint with scope=api.

EnvironmentToken endpoint
Sandboxhttps://auth.sandbox.leantech.me/oauth2/token
Productionhttps://auth.leantech.me/oauth2/token

Replace the placeholders with your application credentials.

curl --request POST \
  --url 'https://auth.sandbox.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'

The response contains the token and its expiry:

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "api"
}

expires_in is the number of seconds until the token expires. Use the returned value to manage its lifetime rather than hard-coding a duration.

Generate Access Token API reference →

2. Make an authenticated API request

Include the backend token in the Authorization header:

Authorization: Bearer <ACCESS_TOKEN>

For example, create a Lean Customer using a unique reference from your own system:

curl --request POST \
  --url 'https://sandbox.leantech.me/customers/v1' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_user_id": "sandbox_user_001"
  }'

Store the returned customer_id against your user record. Reuse that Customer for subsequent interactions.

This is a minimal customer-creation example. Your product flow may require additional customer information, such as government identifiers or a name.

Create Customer API reference →

3. Generate a customer token

When the customer is ready to start a Link SDK journey, request a token from your backend with scope=customer.<customer_id>.

curl --request POST \
  --url 'https://auth.sandbox.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>'

Replace <CUSTOMER_ID> with the Lean Customer ID stored for the signed-in user.

Before issuing the token to your frontend, verify that the signed-in user owns the corresponding customer record. Resolve this mapping on your backend rather than trusting a customer ID supplied by the frontend.

4. Pass the customer token to the Link SDK

Pass the returned token as access_token in the SDK method for your product flow.

The following snippet shows the shared authentication configuration for the Web SDK. Combine it with the fields required by the method you are calling.

const sdkAuthentication = {
  app_token: "<LEAN_APP_TOKEN>",
  customer_id: "<CUSTOMER_ID>",
  access_token: "<CUSTOMER_ACCESS_TOKEN>",
  sandbox: true
};

The token's customer scope must correspond to the customer whose journey you are opening.

Pass only the raw token as the SDK's access_token. Do not add Bearer —the SDK adds the header prefix itself.

The Link SDK requires at least 10 minutes of remaining token validity when it is called. Request a customer token shortly before opening the journey, especially if the customer may have spent time on an earlier screen.

Web SDK guide →

Manage token expiry and credentials

  • Cache backend tokens: Reuse an API token until shortly before its expiry instead of generating one for every request.
  • Obtain a new token when needed: Repeat the client credentials request using the appropriate scope.
  • Keep token caches separate: Separate tokens by application, environment and scope. Customer tokens must also remain associated with the correct customer.
  • Protect secrets and tokens: Store your client secret in a secrets manager and exclude credentials and access tokens from logs, URLs and source control.
  • Coordinate secret rotation: Generating a replacement client secret invalidates the previous secret. Update the backend configuration that requests new tokens.

Troubleshoot authentication

IssueWhat to check
The token request failsSend client_id, client_secret, grant_type and scope in the form-encoded body. Use your Application ID and current client secret, not your webhook secret. Check the environment and OAuth enablement.
An API request returns 401Check the token's expiry, environment and scope. Use an API-scoped token and the header Authorization: Bearer <ACCESS_TOKEN>, including the space after Bearer.
The SDK rejects the tokenPass a customer-scoped token as the raw access_token, without a Bearer prefix. Check that it belongs to the intended customer.
The SDK reports insufficient token validityRequest a new customer token immediately before calling the SDK. It needs at least 10 minutes of remaining validity.
Token generation stops working after secret rotationCheck that every backend instance uses the replacement client secret.

Token request errors

An unsuccessful token request may return an error such as:

{
  "timestamp": "2026-10-16T06:26:29.259896324Z",
  "status": "INVALID_PARAMETERS",
  "message": "invalid_request",
  "metadata": null
}

If you receive invalid_request, check the token request parameters and configuration described above.

Before continuing, confirm that you can generate an API token, create a sandbox Customer and generate a token scoped to that Customer.



Did this page help you?