OAuth 2.1

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

Authorization URL

http://localhost:3002/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 http://localhost:3002/api/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.