Authentication

POPFAB uses API keys to authenticate all requests. Keys are scoped per merchant and environment.

API Keys

Every request to the POPFAB API must include an API key in the Authorization header using the Bearer scheme.

HTTP Authorization headerbash

Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠

API keys grant full access to your merchant account. Never commit them to source control or expose them in client-side code. Use environment variables (e.g. POPFAB_API_KEY).

Environments

POPFAB has two environments. The environment is determined entirely by which API key you use — there is no separate base URL.

Environment	Key Prefix	Description
Sandbox	`sk_test_`	All provider calls are simulated. No real money moves. Data is isolated from live.
Live	`sk_live_`	Real payments processed. Requires your merchant account to be approved for live access.

Managing API Keys

You can create, rotate, and revoke API keys programmatically or through the dashboard.

Create an API key

POST

/v1/api-keys

Requires Owner or Admin role.

Parameter	Type	Required	Description
`label`	`string`	Required	Human-readable label for this key (e.g. "Production Server").
`environment`	`"live" \| "sandbox"`	Required	The environment this key should be valid for.
`rate_limit_max`	`integer`	Optional	Maximum requests per minute. Defaults to the plan limit.

Create an API keybash

curl -X POST https://api.popfab.io/v1/api-keys \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Production Server",
    "environment": "live"
  }'

Responsejson

{
  "id": "key_01HX9T2K",
  "key": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "sk_live_xxxx",
  "label": "Production Server",
  "environment": "live",
  "rate_limit_max": 1000,
  "created_at": "2025-03-19T10:00:00.000Z"
}

The full API key is only returned once at creation. Store it securely immediately. If lost, rotate the key to generate a new one.

Rotate a key

POST

/v1/api-keys/:id/rotate

Generates a new key value. The old key is immediately invalidated.

Rotate an API keybash

curl -X POST https://api.popfab.io/v1/api-keys/key_01HX9T2K/rotate \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

Revoke a key

DELETE

/v1/api-keys/:id

Permanently revokes a key. This action is irreversible.

Rate Limits

Rate limits are enforced per API key. When exceeded, the API returns 429 Too Many Requests.

Plan	Default Limit	Header
Starter (₦0–₦50M GMV)	300 req/min	`X-RateLimit-Limit`
Growth (₦50M–₦500M GMV)	1,000 req/min	`X-RateLimit-Remaining`
Scale (₦500M–₦5B GMV)	5,000 req/min	`X-RateLimit-Reset`
Enterprise	Custom

Team & Roles

Each merchant account supports multiple users with role-based access control.

Role	Permissions
`owner`	Full access. Can manage billing, team, and all settings.
`admin`	Full API access. Can manage team and API keys. Cannot change billing.
`developer`	Read/write API access. Cannot manage team or billing.
`finance`	Read-only access to transactions, reporting, and reconciliation.
`viewer`	Read-only access to transactions and dashboard.

← Quick StartNext: Payments API →