Authentication
Betavend uses API keys to authenticate requests. All API calls must include a valid key in the Authorization header.
Overview
Every request to api.betavend.com must be authenticated using a Bearer token. Your API key identifies your account and determines your rate limits, permissions, and which environment (test or live) the request runs in.
API keys are linked to your Betavend account. You can manage all your keys from business.betavend.com/api-keys or via the POST /v1/keys endpoint.
Get an API Key
- Create a Betavend account at app.betavend.com/register
- Complete KYC verification in your profile
- Visit business.betavend.com/api-keys
- Click Create API Key, give it a name, choose environment
- Copy the key immediately — it is shown only once
Your API key is shown only once at creation time. If you lose it, revoke it and create a new one. Betavend staff will never ask for your API key.
Using Your Key
Pass your API key in the Authorization header as a Bearer token:
Authorization: Bearer bv_live_your_api_key_hereFull example request:
curl https://api.betavend.com/v1/account \
-H "Authorization: Bearer bv_live_abc123..."{
"success": true,
"message": "Success",
"data": {
"id": 1,
"name": "Shuaib Akanbi",
"email": "you@example.com",
"phone": "+2347012345678",
"tier": "pro",
"kyc_level": 2,
"created_at": "2026-01-01T00:00:00.000000Z"
},
"request_id": "2d37ae02-a43d-4e85-8e59-8cbf3c2e49e5"
}Environments
Betavend supports two environments. Use the correct key prefix to target the right environment:
| Environment | Key Prefix | Description |
|---|---|---|
| Live | bv_live_ |
Real transactions, real money. Use in production only. |
| Test | bv_test_ |
Sandbox environment. No real money moves. Perfect for development. |
Never use live keys in development or testing environments. Transactions made with live keys deduct real funds from your wallet.
Key Scopes
Each API key can be scoped to specific permissions. A key with no explicit scopes has access to all endpoints. Scoped keys only have access to the listed operations:
| Scope | Description |
|---|---|
| * | Full access to all endpoints (default) |
| wallet:read | Read wallet balance and transaction history |
| services:purchase | Purchase airtime, data, electricity, TV |
| transactions:read | Read transaction history |
| keys:manage | Create and revoke API keys |
Security Best Practices
- Never expose API keys in frontend JavaScript, mobile app source, or public repositories
- Store keys in environment variables or a secrets manager (AWS Secrets Manager, GCP Secret Manager)
- Set an IP allowlist on your key if your server has a fixed IP
- Rotate keys regularly — use the revoke endpoint to invalidate old keys
- Use test keys during development — never use live keys on a dev machine
- Create separate keys for separate services or environments
Authentication Errors
Bearer bv_Retry-After header.