Authentication
All requests to the Aella for Merchants API must be authenticated using a secret key. We use Bearer Token authentication, which means you'll include your secret key in the Authorization header of every request. This ensures that only authorized applications can access your account and perform operations.
Authentication Overview
The Aella for Merchants API uses Bearer Token authentication to secure all endpoints. This is a standard HTTP authentication method where you include your secret key in the Authorization header. Your secret key acts as your API credentials and should be kept secure at all times.
Base URL
All API requests should be made to:
https://api.aellaapp.com
Authorization Header
Include your secret key in the Authorization header using the Bearer token format:
curl https://api.aellaapp.com/wallets \
-H "Authorization: Bearer your_secret_key"
Secret keys for all environments can be retrieved from the merchant dashboard at https://merchant.aellaapp.com. Always keep your token safe and reset it if you suspect it has been compromised.
Environments
There are 2 environments available:
- Sandbox - For development and testing
- Live - For production use
The same URL (https://api.aellaapp.com) is used for both Sandbox and Live. The API key used is what determines the environment.
Sandbox Environment
- Purpose: The sandbox environment is for development and testing. It allows you to simulate API behavior without affecting real-world data.
- Characteristics:
- No real transactions occur.
- Predefined test scenarios are available (e.g., specific account numbers for testing failures).
- API Key Format:
ae_sk_test_****
Live Environment
- Purpose: The live environment processes actual data and performs real transactions.
- Characteristics:
- Production-grade performance and security.
- Real-world implications for every API call.
- API Key Format:
ae_sk_live_****
Ensure that all API keys are kept secure and that no sandbox credentials are used in the live environment.
IP whitelisting
Merchant API routes can also enforce an IP allowlist. When IP whitelisting is enabled for your organization, requests must come from an allowed IP even if the Bearer token is valid. An unlisted IP receives a forbidden response.
Manage allowed IPs from the merchant dashboard under Settings → API Keys and Webhooks. Add every egress IP your servers use for sandbox and live separately if they differ.
Local development often fails authentication for this reason. Whitelist your current public IP in the sandbox environment before debugging other 401/403 responses.
Request identifiers
Successful and failed responses include an X-Request-Id header. Include that value when contacting support so the request can be located in logs.