Authentication
BillerAPI uses two authentication mechanisms depending on the type of operation.
Authentication Methods
Choose the right method for your use case
Client Credentials
Server-to-server API calls using your client ID and secret.
X-Client-ID + X-Client-SecretAccess Tokens (Bearer)
Per-account tokens from the link token exchange, used for bill retrieval.
Authorization: Bearer <token>Client Credentials
Use client credentials for all server-to-server API calls: biller search, link token creation, webhook registration, and more. Include both headers with every request.
Getting Your Credentials
- Sign up at the Client Portal to create a developer account
- Navigate to Dashboard → API Keys
- Generate a client secret for your target environment
Key Formats
| Environment | Key Prefix | Base URL |
|---|---|---|
| Sandbox | bb_test_* | https://sandbox.api.billerapi.com |
| Production | bb_live_* | https://api.billerapi.com |
Example: List billers with client credentials
const response = await fetch('https://sandbox.api.billerapi.com/billers', {
headers: {
'X-Client-ID': process.env.BILLERAPI_CLIENT_ID,
'X-Client-Secret': process.env.BILLERAPI_CLIENT_SECRET,
},
});
const data = await response.json();Keep secrets safe
Access Tokens (Bearer)
Access tokens are scoped to a single linked account. You obtain them by exchanging the public token returned by the Connect SDK after a user completes the linking flow.
How to Get an Access Token
Create a link token
POST /link/token/create with client credentials
User completes Connect flow
The Connect SDK opens an iframe where the user links their biller account
Exchange the public token
POST /link/token/exchange returns an access_token
Use the access token
Pass as Authorization: Bearer <access_token> for bill retrieval endpoints
Example: Fetch bills with an access token
const response = await fetch(
'https://sandbox.api.billerapi.com/bills/get?account_link_id=link_123',
{
headers: {
'Authorization': `Bearer ${accessToken}`,
},
}
);
const bills = await response.json();Environments
Use the sandbox environment for development and testing. Switch to production when you're ready to go live.
| Environment | Base URL | Description |
|---|---|---|
| Sandbox | https://sandbox.api.billerapi.com | Test billers, deterministic data, no real accounts |
| Production | https://api.billerapi.com | Live billers, real account data |
Note
Error Handling
All errors return a consistent JSON response format.
{
"statusCode": 401,
"message": "Invalid client credentials",
"error": "Unauthorized"
}Common Error Codes
| Status | Meaning | Action |
|---|---|---|
| 401 | Invalid or missing credentials | Check client ID/secret or refresh token |
| 403 | Insufficient permissions | Verify your account has the required scopes |
| 429 | Rate limit exceeded | Back off and retry after the Retry-After period |
| 500 | Internal server error | Retry with exponential backoff; contact support if persistent |
Rate Limits
| Endpoint Group | Limit |
|---|---|
| Authentication | 5 requests / minute per IP |
| Link Operations | 100 requests / minute per client |
| Biller Operations | 200 requests / minute per client |
Security Best Practices
- ✓Store credentials in environment variables, never in source code
- ✓Rotate client secrets periodically via the dashboard
- ✓Use separate credentials for sandbox and production
- ✓Verify webhook signatures before processing events
- ✗Never expose client secrets in frontend code or public repositories
- ✗Never log full credentials — redact secrets in logs