BMM CONNECT DOCUMENTATION

Secure by design. Ready to test.

Keep creators in control while connecting your existing users safely.

Application approval gives your platform credentials, not access to a creator. Each user must approve their connection on BMM. Profile access is read-only; sharing settled earnings is optional and starts unchecked.

If the creator declines earnings, keep the profile and support button available. Treat 403 on earnings as permission denial, not a zero balance. Creators can revoke in BMM → Share → Connected apps. Subsequent authorised reads stop immediately; their account and financial history remain intact.

API key security

Store your API key on the server. Never expose it in public environment variables, browser code, localStorage, logs or an AI prompt. Derive the partner user ID from your authenticated server session. Never let an unauthenticated caller choose whose connection to read.

The SDK's Next.js adapter enforces same-origin POSTs and signs its pending cookies. If you use the core SDK or HTTP API, your backend must implement the same browser-session and request protections. BMM stores hosted connections; do not build a separate BMM token database.

API key rotation invalidates the old key immediately. Update your server and restart pending SDK handshakes. Active hosted connections remain intact; their reads need the new key.

Callback validation

Register exact callback URLs. No wildcards, fragments or embedded credentials. Live requires HTTPS. Sandbox permits localhost and 127.0.0.1 HTTP, but they are different hosts and cannot be interchanged during an attempt.

Create a fresh state and PKCE verifier for each connection. Bind them to the initiating browser and signed-in user. At callback, validate state, the expected issuer, unique callback parameters, the registered callback location and the same partner user before completing. Consume pending state once. Do not continue a request in another user's session.

Hosted issuer: BMM_ORIGIN/api/connect/hosted. Existing OAuth issuer: BMM_ORIGIN/api/auth. The Next.js SDK adapter validates these for the hosted flow. Do not substitute one issuer for the other.

Callbacks carry short-lived codes. Redact query strings from access logs. Keep private API responses uncached. Start a fresh attempt after expiration; never blindly replay a completion or token exchange with an uncertain outcome.

Sandbox and Live

Create separate Sandbox and Live applications. Each has independent credentials, consent and attribution. The app ID selects the environment; do not add an environment override to requests.

Sandbox supports connection and consent testing on the public BMM instance. Payment simulation requires a separately configured payment sandbox. On a live-payment deployment, Sandbox support URLs are null and cannot start live checkout. Do not construct your own checkout URL or use real payments as a substitute for testing.

Test checklist

Connect two users and confirm neither can access the other's profile or earnings.
Sign out or change users while a connection is pending. Completion must fail safely.
Tamper with state, issuer, callback URL and code. Reject duplicates and replayed callbacks.
Open two attempts. Complete the latest one and ensure stale attempts cannot replace it.
Cancel consent. Show a cancellation state without creating an active connection.
Decline earnings permission. Keep the profile and support button, and hide earnings and payment counts.
Revoke through your app and through BMM. Confirm further authorised reads fail.
Rotate a key. Confirm the old key fails and pending handshakes restart.
Check NGN and USD formatting separately, including zeros. Never sum currencies.
Test errors and empty states on mobile, including long application names and code examples.

Troubleshooting

Symptom	Check
Session error	The partner user must be signed in and getUserId must return a stable ID.
Origin error	POST from your configured application origin; keep host and scheme consistent.
State or issuer error	Check callback registration, BMM_ORIGIN, cookie settings and the initiating browser. Restart the attempt.
401 response	Verify approved credentials and whether the key was rotated.
403 on earnings	The creator did not grant permission. Hide earnings, not the profile.
No support URL	Verify the application environment matches the deployment's payment environment.
404 after connection	The connection may be missing or revoked. Offer Connect again.
429 response	Respect Retry-After when present and back off. Avoid retry loops.

See the API error reference for detailed recovery rules.

Going live

Register and obtain approval for your Live application. Configure its separate credentials and exact HTTPS callback on your server. Remove the starter's demonstration browser identity and use your production authenticated session. Keep API keys out of client bundles and logs.

Verify connection, denial, optional earnings and revocation before inviting your first user. Have one developer follow the documentation without assistance and record any unclear steps. Publish only when your normal deployment review is complete.