Authentication
Every request carries an API key as a bearer token. Keys are made and revoked on your account page and are read-only.
Making a key
Sign in, open Account, and find API keys. Give the key a name for the script it is for and create it. The full key is shown once, and only its hash is kept on our side, so copy it straight away. Keys look like bp_live_ followed by 32 characters.
- You can hold up to five keys at once. One per script is a good habit: revoking one then breaks only that script.
- A key can only read the account that made it. It cannot buy, top up, change settings, or rotate your proxy password.
- The account page shows when each key was last used, so an unfamiliar time is a hint that a key has leaked.
Sending it
Put the key in the Authorization header with the Bearer scheme. Query-string keys are not accepted, so they never end up in logs.
curl https://birdieproxies.com/api/me \
-H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"When a key dies
A revoked, mistyped or unknown key gets a 401 with error: "invalid_key", and a missing header gets 401 with error: "missing_key". Both carry a WWW-Authenticate: Bearer header. If you are building a tool that holds keys for other people, a 401 is your cue to ask that customer to make a new key and paste it in again.
{
"error": "invalid_key",
"message": "That API key is not valid or has been revoked. Make a new one under Account, API keys."
}Deleting the account kills every key
When a customer deletes their account, every key on it is removed with it and answers 401 from then on.Keeping it safe
- Read it from an environment variable or a secrets store, never from source control.
- Send it only to
https://birdieproxies.com. Nothing else of ours will ever ask for it. - If it leaks, revoke it on the account page and make another. The old one stops working immediately.