OAuth authorisation

Authentication and parameters

The browser supplies client_id, an exact redirect_uri, random state, code_challenge and code_challenge_method=S256. No API key belongs in this URL. Profile consent is required and earnings consent is optional.

Request and response

Generate a random state and PKCE verifier for every attempt, save them against the initiating user and browser session on your server, and redirect the browser to BMM. The S256 challenge is the base64url-encoded SHA-256 digest of the verifier.

import { randomBytes, createHash } from 'node:crypto';
const state = randomBytes(32).toString('base64url');
const verifier = randomBytes(32).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
const url = new URL('/api/connect/authorize', process.env.BMM_ORIGIN);
url.search = new URLSearchParams({
  client_id: process.env.BMM_CLIENT_ID,
  redirect_uri: process.env.BMM_REDIRECT_URI,
  state, code_challenge: challenge, code_challenge_method: 'S256'
}).toString();
// Persist state/verifier in your server session before redirecting to url.
// The current starter demonstrates hosted connections; existing OAuth clients must retain their own pending state and token storage.

Successful browser authorization returns to the exact registered callback:

http://localhost:3090/api/bmm/callback?code=ONE_TIME_CODE&state=ORIGINAL_STATE&iss=http%3A%2F%2Flocalhost%3A3080%2Fapi%2Fauth

Denial returns the callback with error=access_denied and the original state. Validate state before treating denial as a valid outcome. Before exchanging a successful code, require the exact issuer BMM_ORIGIN/api/auth, not just the origin. Atomically consume the pending request. Codes expire after ten minutes and can be redeemed only once. Exact callback matching and S256 PKCE are mandatory. Never bypass state if the user changed browser/device; ask them to restart.

Errors

400 can indicate an invalid callback or invalid/expired grant. 401 indicates credential or access failure. 403 on earnings means permission was not granted. 429 requires backoff. OAuth errors may contain error and error_description; use status and error code, not matching descriptions. Errors and recovery.