OAuth 2.0 for the Biz Review Radar API

When to use OAuth vs API keys

Exchange a client ID and secret for a short-lived HS256 access token, then send it as a bearer token to the API. There is no user interaction and no refresh token — request a new token when the old one expires (or a little before).

curl -X POST https://bizreviewradar.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=businesses:read analyses:write"

# Response
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "businesses:read analyses:write"
}

# Then call the API
curl https://bizreviewradar.com/api/v1/businesses \
  -H "Authorization: Bearer eyJhbGciOi..."

The S256 authorization-code flow, consent step, refresh-token rotation, and revocation are implemented, but public app registration is gated by the oauth_authcode_enabled administrator flag and is off in production. Treat the example below as a preview of the intended shape, not a currently open integration path.

# 1. Redirect the user to the authorization endpoint
GET /api/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-app.example.com/callback
  &scope=businesses:read
  &state=RANDOM_STATE
  &code_challenge=S256_CHALLENGE
  &code_challenge_method=S256

# 2. Exchange the returned code for tokens
POST /api/oauth/token
  grant_type=authorization_code
  code=RECEIVED_CODE
  redirect_uri=https://your-app.example.com/callback
  client_id=YOUR_CLIENT_ID
  code_verifier=ORIGINAL_VERIFIER

Interested in an integration that needs this flow? Email sales@bizreviewradar.com so we can review it before enabling anything.

Redirect URI rules

• Redirect URIs are registered per client and matched exactly — no wildcards, no prefix matching.
• HTTPS is required. Fragments are not allowed, and query strings must be part of the registered value.
• The redirect_uri sent to /authorize must be sent again unchanged at token exchange.
• Register every environment you use as its own URI; do not reuse one client across environments.
• Client-credentials clients have no redirect URI — the grant never involves a browser.

Scopes

Request the narrowest set you need. A token can never exceed the scopes granted to its client, and scope checks are enforced server-side on every request.

Token lifetime, refresh, and revocation

• Access tokens are short-lived signed JWTs; check expires_in and refresh ahead of expiry.
• Client-credentials issues no refresh token — simply request a new access token.
• For the authorization-code flow, refresh tokens are single-use and rotate on every refresh; reusing an old one invalidates the chain.
• POST /api/oauth/revoke revokes a token. Revoked tokens are rejected on the next API call, so revoke immediately on suspected compromise.
• Rotating or deleting a client's secret invalidates tokens issued to it.

Security requirements

• Client secrets are confidential: keep them server-side, never in browser or mobile code.
• PKCE with S256 is required for the authorization-code flow; plain is not accepted.
• Always send and verify a random, single-use state value.
• All requests must be over TLS. Do not log tokens, codes, or verifiers.
• Store tokens encrypted at rest, and scope them to the smallest set of permissions.
• Handle 401 by re-authenticating once — not in a tight retry loop.

Current status and limitations