Authentication

Every request needs an API key, sent as a bearer token:

Authorization: Bearer <your API key>

Signing in to bonkverse.io doesn't count: requests without a key get 401, even from a logged-in browser.

Get a key

Make your own in the developer portal:

1. Sign in to bonkverse.io (with your bonk.io account).
2. Go to bonkverse.io/developers/keys (also in the menu: Tools → Developer API).
3. Name the key after what it's for, agree to the API terms the first time, and press Create key.
4. Copy it straight away. It's shown once. Bonkverse only stores a fingerprint of it, so a lost key can't be shown again: revoke it on the same page and make another.

You can have up to 3 active keys, one per site or bot. Keys made in the portal are standard keys; for higher limits, see key tiers.

What a key looks like

bvk_ab12cd34_Xq3...43 characters...
    └──┬───┘ └──────┬──────┘
    prefix       secret

The prefix (bvk_ab12cd34) is safe to share: use it when you ask for help. The secret is the password. Never post the whole key.

Keep it secret

• Call the API from your server or bot, not from browser JavaScript. Anything in a web page can be read by anyone who opens it.
• Keep it in an environment variable or your host's secrets settings, not in git.
• If a key leaks, revoke it in the portal and make a new one. Revoked keys stop working immediately.

Key tiers

Tier	For	Limits
standard	Most sites and bots	60 reads/min, 10 bulk lookups/min
partner	Sites we work with directly	300 reads/min, 30 bulk lookups/min

For a partner key, ask on the Bonkverse Discord with what you're building (and a link), roughly how many players you look up and how often, and your key's prefix. Partner keys are set up by hand.

Errors

Status	error	Meaning
401	missing_api_key	No Authorization: Bearer … header
401	invalid_api_key	The key is wrong, malformed or revoked
429	rate_limited	Too many failed key checks from your IP; wait retry_after seconds

Both 401s include "auth": "api_key".