Authenticating with OAuth 2.0
Prerequisites
Basic knowledge of HTTP and REST APIs. An active Aelix developer account with an application registered.
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