Authentication

API keys

API keys are generated per business and scoped to an environment. Each key is permanently linked to the business that created it and acts as its identity on every request.

Key format	Environment	Behaviour
`sk_test_<id>`	Staging	No real money moved
`sk_live_<id>`	Production	Live transactions

Generate keys from Settings → API Keys in the Capera dashboard. You can reveal your live key at any time by re-entering your account password.

Treat API keys like passwords. Anyone who holds your key can make transactions on behalf of your business.

Making authenticated requests

Pass your API key in the Authorization header on every request that requires authentication:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

cURL example

curl https://api.withcapera.com/b2b/v1/transfers/initiate \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

How authentication works

When you make a request, Capera looks up the API key and resolves the business session associated with it. The session carries your businessId, which scopes all data returned — customers, transfers, deposits, webhooks — to your business only.

Sessions are long-lived and backed by the key itself. You do not need to log in, refresh tokens, or manage session state. The API key is the session.

If the API key is valid but its backing session has been cleared (for example after a platform maintenance), Capera automatically recreates the session on the next request. This is transparent to your integration.

Public endpoints

These endpoints do not require an API key:

Method	Endpoint	Description
`GET`	`/health`	API health check
`GET`	`/version`	API version info
`GET`	`/v1/banks`	List available NGN banks
`GET`	`/v1/momo/operators/:country_code`	List MoMo operators

Authenticated endpoints

All other endpoints require the Authorization header. Omitting it returns:

{
  "message": "invalid token"
}

HTTP status: 401 Unauthorized

Error responses

Scenario	Response body	Status
Missing `Authorization` header	`{ "message": "invalid token" }`	`401`
Malformed or incorrect key	`{ "message": "invalid token" }`	`401`
Expired key	`{ "message": "expired token" }`	`401`

Security best practices

Store keys in environment variables or a secrets manager
Use different keys for staging and production
Restrict access to keys to only the services that need them
Rotate your live key periodically from the dashboard

Don't

Embed keys in client-side code or mobile apps
Commit keys to version control
Share keys across teams without access controls
Log full Authorization headers in your application

Key rotation

To rotate your live API key:

Generate a new live key in the dashboard (requires password confirmation)
Update your application's environment variable to the new key
Deploy the update
Verify requests are succeeding with the new key
The old key is invalidated immediately upon generating a new one

There is one live key and one test key per business at any time. Generating a new key replaces the existing one.