Volleyball API authentication

Authentication

Every call carries your key in a header. Keys are made in your account, shown once, and can be rotated or revoked at any time.

Getting a key

Sign in with Google at volleyballapi.com/signup. Your first key is made on the spot on the free plan; it starts with vba_ and is 40 characters long. It is shown once, so keep it somewhere safe. From your account you can make more keys, rotate one, or revoke it.

Sending it

Use either header. Both work on every endpoint.

Header	Example
`Authorization`	`Bearer vba_6c1f...e9`
`X-API-Key`	`vba_6c1f...e9`

# Check your key and your plan
curl "https://api.volleyballapi.com/v1/usage" \
  -H "Authorization: Bearer $VBA_KEY"

$ch = curl_init('https://api.volleyballapi.com/v1/usage');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('VBA_KEY')],
    CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);
print_r($res['data']);

import os, requests

r = requests.get(
    "https://api.volleyballapi.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['VBA_KEY']}"},
)
print(r.json()["data"])

const res = await fetch("https://api.volleyballapi.com/v1/usage", {
  headers: { "X-API-Key": process.env.VBA_KEY },
});
const { data, meta } = await res.json();

Never in the address

A key sent as ?key= or ?api_key= is refused with a 400 before anything else happens. Addresses end up in logs, browser history and proxies; headers do not.

From a browser

The API answers from any origin (CORS), so a key works from a page. Anyone can read a key in a page's code, though: for a public site, call the API from your server, or use a key you are ready to rotate.

When it goes wrong

HTTP	Code	When
401	`unauthorized`	No key, or a key that is not known or was revoked
400	`bad_request`	A key sent in the address

PreviousIntroduction NextResponses and errors