OAuth tokens

Authentication and parameters

Send client_id and client_secret in the form body. For a code exchange include grant_type, redirect_uri, code and code_verifier. For refresh include grant_type and refresh_token. Granted scopes determine subsequent access.

Request and response

Use application/x-www-form-urlencoded, not JSON. Exchange on your server:

curl "$BMM_ORIGIN/api/connect/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "client_id=$BMM_CLIENT_ID" \
  --data-urlencode "client_secret=$BMM_API_KEY" \
  --data-urlencode "redirect_uri=$BMM_REDIRECT_URI" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "code_verifier=$CODE_VERIFIER"

{
  "access_token": "OPAQUE_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "OPAQUE_REFRESH_TOKEN",
  "scope": "profile:read support:read offline_access"
}

support:read is absent when the creator declines earnings sharing. Additional OAuth fields may be returned; do not require an exact set of response keys. Store credentials encrypted, and compute expiry from expires_in. Access tokens last one hour. Refresh credentials have a configured 30-day lifetime, subject to underlying BMM session checks and revocation; access is not guaranteed for 30 days.

curl "$BMM_ORIGIN/api/connect/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "client_id=$BMM_CLIENT_ID" \
  --data-urlencode "client_secret=$BMM_API_KEY" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

Refresh returns the token response shape above. Serialize refreshes per connection and atomically store the replacement access and refresh tokens. Replaying an old code or refresh token can invalidate associated credentials. After an uncertain refresh outcome (timeout/crash after sending), reconnect rather than blindly replaying the old refresh token.

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.