Authentication

Learn how to authenticate with the ILAL API

Two Authentication Methods

Every protected ILAL endpoint accepts either of these two methods. You only need one per request.

API Key (Server-to-Server)

X-API-Key: ilal_live_...

Best for backend services, SDKs, and CI/CD pipelines. Create keys in the API Keys dashboard.

JWT Token (Frontend / Dashboard)

Authorization: Bearer eyJhbG...

Best for browser-based apps and the ILAL Dashboard. Obtain a token via POST /auth/login.

Examples

Using API Key:

curl -X POST https://ilal-mvp-production.up.railway.app/api/v1/defi/swap \
  -H "X-API-Key: ilal_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"tokenIn":"0x...","tokenOut":"0x...","amount":"1000","zeroForOne":true,"userAddress":"0x..."}'

Using JWT:

curl -X GET https://ilal-mvp-production.up.railway.app/api/v1/usage/stats \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."  \
  -H "Content-Type: application/json"

How the server decides

If X-API-Key header is present, the server uses API Key auth exclusively.
If X-API-Key is absent, it falls back to Authorization: Bearer (JWT).
There is no silent fallback: if your API Key is invalid, the request fails even if you also sent a valid JWT.
Every successful response includes authMethod: "api_key" or "jwt" so you can verify which path was used.

API Key Error Codes

All API Key errors include a machine-readable code field for programmatic handling:

API_KEY_FORMAT_INVALIDKey doesn't match ilal_{test|live}_{48 hex}

API_KEY_PREFIX_NOT_FOUNDNo key with this prefix exists in the database

API_KEY_HASH_MISMATCHKey found but hash verification failed

API_KEY_INACTIVEKey has been deactivated

API_KEY_EXPIREDKey is past its expiration date

API_KEY_SCOPE_MISSINGKey lacks a required permission

Example error response:

{
  "error": "Unauthorized",
  "code": "API_KEY_HASH_MISMATCH",
  "message": "API Key hash verification failed",
  "hint": "Ensure you are using the exact key returned at creation time"
}

Security Best Practices

Use Environment Variables

Never hardcode your API Key in source code. Use environment variables to store sensitive information.

# .env file
ILAL_API_KEY=ilal_live_1234567890abcdef...

# In your code
const apiKey = process.env.ILAL_API_KEY;

Restrict Key Permissions

Create separate API Keys for different environments (development, staging, production).

Rotate Regularly

Periodically rotate your API Keys, especially if you suspect a leak.

Never Expose Your Key

Do not commit API Keys to Git repositories. Do not expose keys in client-side code. Do not share keys in public forums.

Manage Your API Keys

You can create, view, and revoke API Keys from the Dashboard.

Go to API Keys Management