Start
Authentication
The API uses secret API keys sent as a Bearer token. There are no sessions, cookies or OAuth flows to manage.
Sending your key
Authorization: Bearer bv_live_3f9a...Requests without a valid key return 401 invalid_api_key. A key that is revoked, expired or typed wrongly is indistinguishable from a missing one on purpose.
Live and test keys
| Prefix | Environment | What it does |
|---|---|---|
bv_test_ | Sandbox | Separate data, a 5,000,000 NGN play-money wallet, simulated results and separate webhook endpoints. Nothing reaches real people. |
bv_live_ | Production | Real campaigns charged from your real wallet. Campaigns are reviewed by ByteVerse before they run. |
The environment is decided by the key. The same URL and code work for both. Every response carries a ByteVerse-Environment header so you can confirm which one you hit.
Scopes
Keys can be limited to the permissions an integration needs. A reporting dashboard, for example, can have a read-only key that cannot spend money.
| Scope | Allows |
|---|---|
catalog:read | Growth Action types and quotes |
campaigns:read | List and retrieve campaigns |
campaigns:write | Create, pause, resume, cancel (and sandbox simulation) |
performance:read | Performance and summary |
wallet:read | Balance and transactions |
webhooks:manage | Webhook endpoints, deliveries and events |
submissions:read | Anonymous list of submissions on your campaigns |
evidence:read | Proof screenshots for a submission |
Calling an endpoint without the scope returns 403 insufficient_scope. By default keys have all scopes; ask for a restricted key when you need one.
Keeping keys safe
- Server-side only. Browser requests are not supported (CORS is intentionally off) so a key cannot leak through front-end code.
- Store keys in a secrets manager or environment variables, never in source control.
- Use separate keys per service so you can revoke one without breaking the rest.
- We store only a hash of your key, so we cannot show it again. If you lose it we issue a new one and revoke the old.
- If a key might be exposed, email us immediately and we will revoke it.
Webhook secrets are different. A whsec_... secret is used only to verify that webhook calls really came from ByteVerse. See Webhooks.