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"

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": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f",
    "key_prefix": "9f8e7d6c...",
    "tier": "free",
    "daily_limit": 100,
    "expires_at": null,
    "note": "Store this key securely — it will not be shown again."
  }
}

Set it as an environment variable:

export AFRIHEX_API_KEY="9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f"

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" }
}

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.

Plan tiers

Tier	Requests / 24h	Best for
Free	100	Evaluation and prototypes
Basic	5,000	Production apps getting started
Pro	20,000	Growing applications
Enterprise	100,000+	Banks and large platforms

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.