OAuth 2.0 credentials

Overview

Leena AI APIs are not called with your client secret directly. Your integration exchanges its credentials for a short-lived Bearer access token, and sends that token on every subsequent API call.

This page covers the token exchange, how to use the token, and how to refresh it.

Pre-requisites

An Active credential created from Settings → API credentials. See API credentials.
The four values copied from the credential detail screen at creation — Client ID, Client secret, Username and Password. These are shown only once and cannot be retrieved later.
The credential must hold the scope required by the API you intend to call.

Credentials you need

Value	Where it is used
Client ID	Basic authorization header, before the colon
Client secret	Basic authorization header, after the colon
Username	Request body
Password	Request body

The Authorization header is the Base64 encoding of clientId:clientSecret.

Note: The credential detail screen renders a ready-to-run command under How to use this key, with your Client ID and secret already encoded. Copy it at creation time, while the secret is still visible.

Step 1 — Generate an access token

Method: POST
Endpoint: /api/v1.0/oauth/token
Content-Type: application/json
Authorization: Basic <base64 of clientId:clientSecret>

Request body

{
  "username": "<username>",
  "password": "<password>",
  "grant_type": "password"
}

Example

curl --location 'https://acl.leena.ai/api/v1.0/oauth/token' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <base64 of clientId:clientSecret>' \
  --data '{
    "username": "<username>",
    "password": "<password>",
    "grant_type": "password"
  }'

Note: The host is region-specific. Use the host shown in the How to use this key command on your credential detail screen rather than copying the example above.

Response

Field	Description
`access_token`	The Bearer token to send on API calls.
`refresh_token`	Used to obtain a new access token without re-sending the password.
`token_type`	Always `Bearer`.
`expires_in`	Lifetime of the access token in seconds. `1800` (30 minutes) unless a custom validity has been configured for your credential.

Step 2 — Call a Leena AI API

Send the access token as a Bearer token on each request:

Authorization: Bearer <access_token>

The token carries the scopes assigned to the credential. A call to an API outside those scopes is rejected as unauthorized, even though the token itself is valid.

Step 3 — Refresh the access token

Access tokens expire after 30 minutes. Use the refresh token rather than repeating the password grant on every call.

Method: POST
Endpoint: /api/v1.0/oauth/refresh-token

Request body

{
  "refresh_token": "<refresh_token>"
}

A new access token is returned. Build refresh handling into your middleware so long-running jobs do not fail when a token expires mid-run.

Token lifecycle

Behaviour	Detail
Access token validity	30 minutes by default. Refresh before expiry rather than re-authenticating.
Refresh token validity	30 days from the time it was issued.
On rotation	Changing the client secret or password invalidates every refresh token issued before that change. Re-run Step 1 to obtain a fresh pair.

Security: If you believe a credential has been exposed — committed to a repository, shared in a ticket, or captured in a screenshot — contact Leena AI support in addition to revoking it from the dashboard, so the credential can be fully retired.

Troubleshooting

Symptom	Likely cause
`401 Unauthorized` on the token call	Incorrect `clientId:clientSecret` in the Basic header, or incorrect username or password in the body.
`Invalid grant type`	`grant_type` must be `password` for the initial token call.
`401` on the refresh call	The refresh token has expired, or the credential's secret or password was rotated after that token was issued.
`401` or `403` on a data API with a valid token	The credential does not hold the scope that endpoint requires. Create a new credential with the correct scope.

Updated about 1 hour ago

Did this page help you?