Four steps. Two of them are copy-paste. There is no CLI to install and nothing to configure with any provider.
Every sample here uses {tenantName} as a placeholder. Once you log in, your configuration screen shows this same guide with your own tenant name and API key already filled in, ready to paste.
Copy the prompt that matches your project, paste it into your coding agent, and replace the placeholders with your tenant name and API key.
First-time setup
Add Login Broker social authentication to this project.
1. Inspect the existing frontend and backend architecture and follow its conventions.
2. Load https://login.broker/analytics-v4.js on pages that initiate login. Choose ?mode=popup or ?mode=redirect to fit the app.
3. Create a Login Broker instance with tenant name {tenantName}, the selected provider, a completion callback, and an error callback.
4. Start login only from an explicit user action. On completion, send the returned sessionId to this application's backend.
5. In the backend, call GET https://login.broker/{tenantName}/auth/result/{sessionId} with Authorization: Secret {yourApiKey}.
6. Keep the API key server-side in environment configuration. Never expose it to browser code or commit it.
7. Accept the login only when the response is successful, status is completed, and an email is present. Use that verified email to find or create the local user and establish this application's own session.
8. Add appropriate loading, cancellation, expiry, and error UI. Preserve the application's existing authentication behavior where it is unrelated to Login Broker.
9. Add focused tests for the backend verification handler and report the files changed and checks run.
Migrate to v4
Migrate this project to Login Broker v4 without changing its tenant name, API key, user records, or application session behavior.
1. Find every older Login Broker script reference and replace it with https://login.broker/analytics-v4.js. Preserve the intended ?mode=popup or ?mode=redirect setting.
2. Find every server-side Login Broker verification URL and change it from https://api.login.broker/{tenantName}/auth/result/{sessionId} to https://login.broker/{tenantName}/auth/result/{sessionId}. Keep the Authorization: Secret {yourApiKey} header.
3. Do not construct provider-specific hosts such as google.login.broker. V4 starts the visible login flow on social.login.broker automatically.
4. Check the v4 completion callback handling. It receives a sessionId that must still be sent to this application's backend for verification.
5. Keep the API key server-side and do not expose or log it.
6. Remove obsolete v1-only code only when it is no longer referenced.
7. Test the selected popup or redirect flow, backend verification, error handling, and existing-user login. Report the files changed and checks run.
1. Choose a tenant name
A short lowercase identifier for your company or app — letters only, no spaces or special characters. It appears in every API URL, and it cannot be changed later.
GOODacmehqredditnetflixNOmy-app-2Acme Inc
2. Fetch your API key
The key appears in the configuration screen as soon as the tenant name is saved. It is a server-side secret: it authorises the result endpoint that returns verified email addresses. Never put it in client code.
API KEYshown in your configuration screen
3. Add it to your site
One script tag, no build step, no package to install.
Then create an instance and start the flow from your button's click handler. The SDK opens the provider, watches the session, and calls you back with a sessionId.
login.js
// called when the login has completed
function handleSessionReceived(sessionId) {
// send it to your own API to be verified
fetch('/api/login', {
method: 'POST',
body: JSON.stringify({ sessionId })
});
}
function handleErrorReceived(error) {
console.log('Error happened:', error);
}
const broker = useLoginBroker(
'{tenantName}', // the name you chose
'google', // the provider
handleSessionReceived,
handleErrorReceived
);
document.querySelector('#google-btn')
.addEventListener('click', () => broker.startLoginProcess());
4. Verify the login server-side
A sessionId is not proof of anything on its own. The client cannot verify itself — the exchange below must happen in your server-side code.
Call the result endpoint with your API key in the Authorization header. If your HTTP client insists on a scheme, use Secret.
request
GET https://login.broker/{tenantName}/auth/result/{sessionId}
Authorization: Secret {yourApiKey}
200 response
{
"email": "the fully verified email of the user",
"tenantName": "{tenantName}",
"platform": "google",
"status": "pending | failed | completed",
"error": ""
}
An email with status completed means the user is properly authenticated. If they have no account yet, the recommended move is to sign them up automatically on that first login.
Popup or redirect
Popup is the default. Append a query parameter to the script URL to switch to a full-page redirect, which is the safer choice on mobile browsers that block popups.
Opens a new tab and posts the result back to your page. Your app state stays exactly where it was.
redirect
Navigates away and returns to the current URL. The pending session is stored and resumed automatically on load, then the query parameters are cleaned up.
Providers
The second argument to useLoginBroker is one of these exact strings. To offer several buttons, create one instance per provider.
googlefacebookmicrosoftapplelinkedingithub
HTTP API
GET /{tenantName}/auth/{platform}/session/{sessionId}
Starts a login. Creates the session and redirects the browser to the provider. Accepts an optional returnUrl for redirect mode. Public.
GET /{tenantName}/auth/status/{sessionId}
Returns the bare status string — pending, completed or failed. No email, so it is safe to poll from the client. Public.
GET /{tenantName}/auth/result/{sessionId}
Returns the full session including the verified email. Requires the API key in the Authorization header. Server-side only.
base url https://login.broker
Custom implementation
You do not have to use the SDK. It is roughly 200 lines doing four things, and any of them can be yours:
Generate a random 15-character alphanumeric sessionId.
Open https://social.login.broker/{tenant}/auth/{platform}/session/{sessionId} in a popup, or navigate to it with a returnUrl.
Poll the status endpoint until it returns completed — or listen for the postMessage from the popup.
Exchange the session for the email from your server.
Errors and expiry
404The sessionId is unknown. Usually a typo, or a session from a different tenant.
410The session is older than 10 minutes. Start a new login.
400The tenant name does not exist in Login Broker.
failedThe user abandoned the provider screen, or the provider rejected the request. Show your button again.
The SDK polls every 2 seconds and gives up after 60 attempts, so a session that is never completed resolves to an error after about two minutes.