BMM CONNECT DOCUMENTATION

Start a connection

Create a secure connection attempt for your signed-in user.

POST/api/connect/hosted/start

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.

No creator permission is required to initiate a request. The creator must explicitly approve it before access becomes active.

Parameters

JSON body; all fields are required.

Field	Value
partner_user_id	Your authenticated user's stable ID, 1–256 characters.
redirect_uri	An exact approved callback URL, at most 2,000 characters.
state	A fresh 32-byte random value encoded as 43 base64url characters.
code_challenge	The base64url SHA-256 digest of your random verifier, 43 characters.

The SDK manages the browser cookie and PKCE. For custom server integrations, generate cryptographically random 32-byte base64url state and verifier, retain them in an authenticated HttpOnly browser cookie bound to the current partner user, and calculate the base64url SHA-256 verifier challenge.

Request

curl "$BMM_ORIGIN/api/connect/hosted/start" -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","state":"REPLACE_WITH_43_CHARACTER_RANDOM_STATE","code_challenge":"REPLACE_WITH_43_CHARACTER_S256_CHALLENGE"}'

Success response

json

{"authorization_url":"https://buymeamalt.com/connect/login?hosted=OPAQUE_REQUEST","expires_in":600}

Next step

Redirect the browser to authorization_url. The attempt lasts 600 seconds. Starting again invalidates the previous unfinished attempt for that application/user. After consent, validate and complete the callback. Retain state and verifier in an authenticated HttpOnly cookie bound to the initiating user and browser. The Next.js adapter does this for you.

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