OAuth 2.1

8BALL supports authorization code with PKCE for user-facing apps. Public clients must use code_challenge_method=S256.

Authorization URL

https://dev.8ball.live/oauth/authorize?response_type=code&client_id=8b_client_...&redirect_uri=https://example.com/callback&scope=user:read channel:read&state=random&code_challenge=...&code_challenge_method=S256

After consent, 8BALL redirects back with code and state.

Token Exchange

curl -X POST https://api.8ball.live/oauth/token \
  -u "8b_client_...:8b_secret_..." \
  -d grant_type=authorization_code \
  -d code=8b_code_... \
  -d redirect_uri=https://example.com/callback \
  -d code_verifier=original-verifier

The response includes a Bearer access token, expiry, scopes, and a refresh token.

Refresh Token

curl -X POST https://api.8ball.live/oauth/token \
  -u "8b_client_...:8b_secret_..." \
  -d grant_type=refresh_token \
  -d refresh_token=8b_rt_...

Client Credentials

Server-to-server integrations can request app-scoped tokens:

curl -X POST https://api.8ball.live/oauth/token \
  -u "8b_client_...:8b_secret_..." \
  -d grant_type=client_credentials \
  -d scope=channel:read livestream:read

Revoke Token

curl -X POST https://api.8ball.live/oauth/revoke \
  -u "8b_client_...:8b_secret_..." \
  -d token=8b_at_...

Returns 204 No Content on success.