Crea per il gioco.

Authentication

Every data call carries a bearer token that stands for one manager:

Authorization: Bearer <token>

There are two kinds of token, for two kinds of software.

Tokens, codes and secrets are random 256-bit values stored by the game only as SHA-256 hashes: the game cannot show a token again, and nobody who reads its database can use one.

Personal tokens

Make one in the game and send it as the bearer token — that is all. You can hold up to 10 at once. Revoke a token you no longer use; revoked or expired tokens answer 401.

Personal tokens are for you. Never ask other managers for theirs: a tool that other people use must be a registered application, so each manager can see it, choose its scopes and revoke it on their own.

Applications

1. Register

In the game: Settings → API & third-party apps → My applications → Register. You give:

• Name, description, website — shown to managers on the sign-in page. Say plainly what the tool does.
• Kind
  • Confidential — the tool has a server that can keep a secret (a website with a backend). You get a client secret (bbcs_…), shown once; rotate it any time.
  • Public — the tool runs on the manager's own computer or phone (desktop app, mobile app, CLI) and cannot keep a secret. It proves itself with PKCE alone.
• Redirect URIs (up to 5), where the sign-in page sends the manager back:
  • https://… for web applications, matched exactly;
  • http://127.0.0.1/callback or http://localhost/callback for desktop tools — any port is accepted for loopback addresses, so the tool can listen on a free port (RFC 8252);
  • a private-use scheme named after a domain you own, such as com.example.bbtool:/callback, for mobile apps.

A new application is in development: it works, but only for your own account and on the development quota. When it is ready, ask for a review (see Terms); once staff approve it, any manager can sign in to it and it gets the full quota.

You get a client id (bbc_…). It is public and goes in every sign-in link.

2. Send the manager to the sign-in page

Create a PKCE pair for every sign-in: a random code_verifier (43–128 characters of A–Z a–z 0–9 - . _ ~) and its code_challenge = BASE64URL(SHA256(code_verifier)) without padding. Keep the verifier, and a random state to recognise the answer.

https://play.buzzerbeater.com/oauth/authorize
  ?response_type=code
  &client_id=bbc_Yx3…
  &redirect_uri=https%3A%2F%2Fmytool.example%2Fcallback
  &scope=public%20team
  &state=4b1f…
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

code_challenge_method=S256 is required; plain is refused. Ask only for the scopes the tool really uses — the list is shown to the manager, and a short list gets more yeses. If the manager is not signed in to the game, they sign in first and come back to the same page.

A manager who already allowed your tool every scope you ask for is not asked again: the page sends them straight back to your redirect URI with a new code. Asking for a scope they have not granted yet shows the page again, listing all the scopes. Add &prompt=consent to show the page anyway, for example behind a "switch account" or "review permissions" button.

3. Receive the code

If the manager allows the tool, the browser returns to your redirect URI:

https://mytool.example/callback?code=bbac_…&state=4b1f…

If they deny it: ?error=access_denied&state=4b1f…. Check that state is the one you sent. The code is good once, for 5 minutes.

4. Trade the code for tokens

curl -s https://sb1-api.buzzerbeater.com/v1/oauth/token \
  -u "bbc_Yx3…:bbcs_…" \
  -d grant_type=authorization_code \
  -d code=bbac_… \
  -d redirect_uri=https://mytool.example/callback \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

A public client sends -d client_id=bbc_… instead of -u, and no secret. The body is application/x-www-form-urlencoded, as OAuth requires.

{
  "access_token": "bbat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "bbrt_…",
  "scope": "public team"
}

5. Refresh

When the access token expires (the API answers 401), trade the refresh token for a new pair:

curl -s https://sb1-api.buzzerbeater.com/v1/oauth/token \
  -u "bbc_Yx3…:bbcs_…" \
  -d grant_type=refresh_token \
  -d refresh_token=bbrt_…

Refresh tokens rotate: each is good once, and the answer holds the next one. Store the new refresh token before you use the new access token. If a spent refresh token is ever presented again, the game assumes it was stolen and revokes the whole chain — the manager then has to sign in again. So never refresh the same token from two places at once; serialise refreshes in your tool.

You may pass scope to narrow the scopes of the new pair; you can never widen them without sending the manager through the sign-in page again.

6. Sign out

curl -s https://sb1-api.buzzerbeater.com/v1/oauth/revoke \
  -u "bbc_Yx3…:bbcs_…" \
  -d token=bbrt_…

Revoking a refresh token revokes its whole chain, access tokens included. The endpoint answers 200 whether or not the token was known (RFC 7009).

Errors of the token endpoint

They follow RFC 6749: {"error": "...", "error_description": "..."}.

The token endpoint takes at most 20 requests a minute per address.

Security checklist

• Use PKCE on every sign-in, even with a client secret.
• Check state on the way back.
• Keep client secrets and refresh tokens on a server or in the operating system's secure storage — never in a browser, a mobile app's code, a public repository or a log.
• Rotate the client secret if it may have leaked (My applications → Rotate secret); the old one stops working at once.
• Handle 401 by refreshing once, then by signing the manager in again.