Authenticating with OAuth 2.0

Overview

Aelix APIs use OAuth 2.0 Client Credentials for server-to-server authentication. This flow is ideal for background services and daemons that need to access APIs without user involvement.

Step 1 — Register Your Application

In the Developer Portal, navigate to Dashboard → Applications → Register App. Fill in:

• App Name — a unique identifier for your application
• Grant Types — select Client Credentials
• Scopes — choose only the scopes your app requires

After saving, the portal will display your client_id and client_secret. Store these in your environment's secret manager.

Step 2 — Request an Access Token

Send a POST request to the token endpoint:

POST https://auth.aelix.digitalapi.ai/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=banking:read payments:write

A successful response returns:

{
"access_token": "eyJhbGciOiJSUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "banking:read payments:write"
}

Step 3 — Use the Token in API Requests

Include the token in the Authorization header for every API call:

GET https://api.aelix.digitalapi.ai/v1/accounts
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
Accept: application/json

Step 4 — Handle Token Expiry

Access tokens expire after 3,600 seconds (1 hour). Best practice is to cache the token and refresh it 60 seconds before expiry to avoid 401 errors mid-request.

// Pseudocode
if (token.expires_at - now() < 60) {
token = requestNewToken();
cache.set('oauth_token', token);
}

Security Tips

• Never log access tokens or commit client_secret to source control
• Request only the scopes your application actually needs
• Rotate client secrets every 90 days
• Use HTTPS for all requests — token interception over plain HTTP is trivial