Authentication
All /v2/* endpoints require an API key. Authenticate by sending your key in
the X-API-Key header on every request:
curl "https://api.afrihex.com/v2/lookup?address=GA-142-7281" \
-H "X-API-Key: $AFRIHEX_API_KEY"
Keep your API key on your server
Your API key is a secret: anyone who has it can spend your quota and use your paid features. Never put it in code that runs on someone else's device.
- Web dashboards: have the browser call your backend, and your backend
call AfriHex with the key. Don't call
api.afrihex.comwith your key from browser JavaScript; it is visible in the page source and network tab. - Mobile and rider apps: the same rule applies. Keys shipped inside an app can be extracted. Route requests through your server.
- Store it as configuration, such as an environment variable or a secrets manager, not in your source code or repository.
- If a key leaks, rotate it straight away (see Key management).
Your dashboard / app → your backend (holds AFRIHEX_API_KEY) → api.afrihex.com
Get a key — self-service signup
Create a free-tier key in one call. No password needed. The key is returned once and emailed to you, so store it securely.
POST /v2/self/signup
Request object:
| Parameter | Type | Required | Definition |
|---|---|---|---|
name | string | required | Your name or app name |
email | string | required | Where the key and welcome email are sent |
curl -X POST "https://api.afrihex.com/v2/self/signup" \
-H "Content-Type: application/json" \
-d '{
"name": "Your App",
"email": "you@example.com"
}'
{
"success": true,
"data": {
"id": 1,
"name": "Your App",
"email": "you@example.com",
"key": "afx_live_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f01",
"key_prefix": "afx_live_9f8e...",
"tier": "free",
"daily_limit": 20,
"expires_at": null,
"note": "Store this key securely — it will not be shown again."
}
}
Set it as an environment variable:
export AFRIHEX_API_KEY="afx_live_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f01"
Key format
Keys start with afx_live_ followed by 64 hex characters. The prefix lets
secret scanners spot a key that ends up somewhere it shouldn't, such as a
public repository. To catch AfriHex keys in your own code, add this pattern to
your scanner (for GitHub, a custom pattern under Settings → Code security):
afx_(live|test)_[0-9a-f]{64}
Keys issued before November 2026 are plain 64-character hex and keep working. Regenerate one from your dashboard to get the new format.
Auth errors
If the key is missing, the API returns 401:
{
"success": false,
"error": { "code": "MISSING_API_KEY", "message": "X-API-Key header is required" }
}
If the key is unknown, revoked, or expired:
{
"success": false,
"error": { "code": "INVALID_API_KEY", "message": "invalid or revoked API key" }
}
The lookup, search and routing endpoints used by AfriHex's own apps also
accept an app client key (X-Client-Key) instead of a user key. Client
keys are issued only for AfriHex apps and approved partners — with your own
X-API-Key you never need one. A call that sends neither gets:
{
"success": false,
"error": { "code": "CLIENT_KEY_REQUIRED", "message": "sign in, or send an X-Client-Key header" }
}
Some endpoints also require an account-scoped key — a legacy key returns:
{
"success": false,
"error": { "code": "ACCOUNT_KEY_REQUIRED", "message": "this endpoint requires an account API key; legacy keys without an account identity cannot access tenant data" }
}
Key management
| Endpoint | Purpose |
|---|---|
POST /v2/self/signup | Create a free-tier key |
GET /v2/me | View your key details and usage |
POST /v2/me/rotate | Rotate your key (old key is revoked) |
DELETE /v2/me/key | Revoke your key |
GET /v2/usage | View your usage |
Rotating or revoking a key takes effect immediately:
# View your key metadata + usage
curl "https://api.afrihex.com/v2/me" -H "X-API-Key: $AFRIHEX_API_KEY"
# Rotate (old key is revoked; new key returned once)
curl -X POST "https://api.afrihex.com/v2/me/rotate" -H "X-API-Key: $AFRIHEX_API_KEY"
# Revoke your key
curl -X DELETE "https://api.afrihex.com/v2/me/key" -H "X-API-Key: $AFRIHEX_API_KEY"
# Check usage against your plan
curl "https://api.afrihex.com/v2/usage" -H "X-API-Key: $AFRIHEX_API_KEY"
Keep keys secret — never commit them to source control, and never send them from client-side code where users can see them.
App-user accounts
Separate from a static developer key, the platform also issues per-user tokens for mobile and web apps — one per signed-in user, not one key shared by the whole app:
| Endpoint | Purpose |
|---|---|
POST /v2/auth/login | Email/password sign-in, returns a personal token |
POST /v2/auth/google/mobile | Verify a Google ID token server-side and get a personal token (Android / iOS, no redirect) |
POST /v2/me/password | Attach a password to an OAuth-only account, or change an existing one |
POST /v2/auth/forgot-password | Email a one-time, hashed, 30-minute password reset token |
POST /v2/auth/reset-password | Reset the password with the emailed token |
The token these return is an X-API-Key value, scoped to that one
user — send it in the same header as any other key; it is not a separate
bearer/session scheme. This is the recommended pattern for a mobile app: mint
a token per signed-in user rather than embedding your static developer key in
the app bundle, where it's extractable and shared by every install. See
Mobile Integration for the full pattern.
Banking Suite access
Banking Suite — collections/*, analytics/portfolio-risk, verify/schedule*,
and banking/audit-log — is provisioned per institution, separately from
your plan tier. A Free or Pro key doesn't get it just by having higher rate
limits; it's granted explicitly. An account without it gets:
{
"success": false,
"error": {
"code": "BANKING_ACCESS_REQUIRED",
"message": "this account is not provisioned for Banking Suite — contact us to get set up"
}
}
If your account has an IP allowlist configured (optional, ask us to set one up), a request from outside it gets:
{
"success": false,
"error": {
"code": "IP_NOT_ALLOWED",
"message": "this request's IP address is not on the account's allowlist"
}
}
POST /v2/kyc/verify and POST /v2/verify/proximity are not gated by
this — any authenticated account can call them, same as before. They're
shared with the general-purpose Address Verify product (the embeddable
widget), so Banking Suite provisioning only applies to the lending-specific
tools: collection zone tracking, portfolio risk, re-verification scheduling,
and the audit-log endpoint. See Identity & KYC,
Collections & Service Areas, and
Risk & Fraud for what each covers.
To get an account provisioned (with or without an IP allowlist), contact dominic@afrihex.com.
Plan tiers
| Tier | Requests / 24h | Fleet route planning | Typical use |
|---|---|---|---|
| Free | 20 | — | Evaluation and prototypes |
| Basic | 1,000 | ✓ | Production apps getting started |
| Pro | 5,000 | ✓ | Growing applications |
| Enterprise | 10,000 | ✓ | Larger platforms and fleets |
POST /v2/route/plan (fleet route
planning) is available on paid plans only. See current prices at
maps.afrihex.com/pricing.
See Rate Limits for how quotas are enforced and the headers to monitor.
Local development
In development (ENVIRONMENT=development) authentication may be disabled on
self-hosted instances. Public deployments always require a key.