BMM CONNECT DOCUMENTATION

Complete a connection

Validate the callback and activate the creator's connection.

POST/api/connect/hosted/complete

Authentication and permissions

Send X-BMM-Client-ID and X-BMM-API-Key from your server. The API key authenticates the approved application; creator consent controls access to the account. A key alone does not authorise access to a creator.

The same user must have approved the pending connection. This step activates it only after callback validation.

Validate the callback first

Redirect the browser to authorization_url. Existing BMM sign-in, registration and explicit consent are unchanged. Approval returns code, state and iss to the exact registered callback; denial returns error=access_denied, state and iss. The hosted issuer is BMM_ORIGIN/api/connect/hosted. Validate the unique parameters, browser state, issuer and the same authenticated partner user before completing. Never accept the partner user ID from the callback query.

Do not send a completion request when consent was denied. Clear the pending cookie and show a cancelled state.

Parameters

JSON body; all fields are required.

Field	Value
partner_user_id	The same authenticated user as the start request, 1–256 characters.
redirect_uri	The exact callback used at start, at most 2,000 characters.
code	The one-use 43-character base64url code returned by BMM.
code_verifier	The original 43-character random base64url verifier.

Request

curl "$BMM_ORIGIN/api/connect/hosted/complete" -X POST \
  -H "X-BMM-Client-ID: $BMM_CLIENT_ID" -H "X-BMM-API-Key: $BMM_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"partner_user_id":"player_123","redirect_uri":"https://game.example/api/bmm/callback","code":"REPLACE_WITH_ONE_USE_CODE","code_verifier":"REPLACE_WITH_ORIGINAL_VERIFIER"}'

Success response

json

{"connected":true}

No access/refresh tokens are issued. Requests and codes expire with the ten-minute attempt; completion is single-use. A new start invalidates older unfinished attempts for this application/user. Connections become accessible only after completion. If completion's network outcome is unknown, read the connection; restart if needed, never blindly replay the code. Completing another hosted mapping for the same creator/application replaces the previous hosted mapping. Existing OAuth grants remain separate.

An invalid, expired, replayed or mismatched code returns 400. A revoked pending approval returns 410. After an uncertain result, read the connection before starting again.

Errors

Status	Meaning
400	Invalid request or unavailable application.
401	Missing, invalid or rotated application credentials.
403	Application not approved, or required permission not granted.
429	Rate limited. Honour Retry-After when supplied and back off.
5xx	Temporary failure. Retry reads with backoff.

Errors contain {"error":"message"}. Do not match error text or cache private responses. Full error guide.

← All endpoints