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 tenant-name placeholder. The prompt deliberately contains no API key; the agent will wire a server-side configuration variable and tell you if it still needs a value.
Web — redirect integration
Add or update Login Broker social authentication in this web project for tenant {tenantName}, using redirect mode with a small custom client implementation. Do not load https://social.login.broker/client.js — implement the redirect flow directly in the project's existing frontend code.
The project may have no integration, a partial implementation, or an older Login Broker integration. Inspect only the Login Broker integration points, keep correct existing pieces, update legacy pieces, and add only what is missing. Stay strictly within this integration. Do not refactor unrelated code, redesign authentication or sessions, change UI behavior or configuration strategy, add features, or perform opportunistic cleanup.
1. Locate existing Login Broker script references, login actions, completion and error callbacks, status or result requests, backend verification code, and the server-side API-key configuration variable. Do not broaden the review beyond code directly involved in Login Broker.
2. Login Broker supports these providers, passed as the exact lowercase string in the session URL: google, github, apple, facebook, linkedin, and microsoft. Preserve existing provider choices when they already exist. If this is a new or partial implementation and the provider is not specified, ask the user instead of choosing. When adding or updating login buttons, it is a good idea to show each provider's brand icon alongside its label. Use redirect mode only — do not use popup mode or window.open.
3. From each existing explicit login action, as soon as the user clicks a provider, replace the login options immediately with a panel that says "Please wait" (or equivalent copy in the app's existing tone) so it is clear the redirect has started, then generate a simple GUID as sessionId — do not use crypto, node:crypto, crypto.getRandomValues, or crypto.randomUUID. The sessionId is not a secret and is not sensitive; it only needs to be unique for about 10 minutes, so a trivial GUID or timestamp-plus-random string is enough. Then navigate the browser to https://social.login.broker/{tenantName}/auth/{provider}/session/{sessionId}?returnUrl={returnUrl}. URL-encode the provider and sessionId correctly. Set returnUrl to the current page URL with any loginBrokerSessionId and loginBrokerStatus query parameters removed, passed as the returnUrl query parameter (URL-encoded), so a second login does not carry stale values. Do not send the API key from browser code.
4. On each page used as returnUrl — usually the same page as the login button — run return handling on the client only. In Nuxt, SSR, or similar frameworks, use onMounted, false, or the project's existing client-only guard; URL parameters and history.replaceState are not available during server render. Read loginBrokerSessionId and loginBrokerStatus from the query string. When loginBrokerSessionId is present, do not show the login options again — replace them immediately with a panel that says "Verifying" (or equivalent copy in the app's existing tone) and keep it visible until verification finishes, fails, or times out. Then: if loginBrokerStatus is completed or absent, send that sessionId to the application's backend through the existing completion path; if loginBrokerStatus is pending, or the backend responds with 409 because the session is not ready yet, poll GET https://social.login.broker/{tenantName}/auth/status/{sessionId} every 2 seconds for at most 60 attempts until the result is completed or failed, then verify when completed; if loginBrokerStatus is failed or any other terminal non-completed value, use the existing error-handling path and restore the login options. After handling, remove loginBrokerSessionId and loginBrokerStatus from the URL with history.replaceState.
5. Ensure the completion path sends the sessionId to the application's backend. Do not treat the session ID as authenticated in browser code.
6. In the backend, ensure verification requests GET https://social.login.broker/{tenantName}/auth/result/{sessionId} and set X-LoginBroker-ApiKey from server-side configuration. Replace legacy https://api.login.broker and https://login.broker result URLs and Authorization: Secret headers. Accept the login only when the request succeeds, status is completed, and an email is present, then continue through the application's existing user/session flow unchanged.
7. Replace provider-specific initiation hosts such as https://google.login.broker with https://social.login.broker, and replace status polling at https://api.login.broker/{tenantName}/auth/status/{sessionId} or https://login.broker/{tenantName}/auth/status/{sessionId} with https://social.login.broker/{tenantName}/auth/status/{sessionId}. When migrating from popup mode or client.js, remove https://social.login.broker/client.js script tags, useLoginBroker / loginbroker:ready wiring, window.open login flows, and any popup-only UI such as AuthWindow components superseded by this direct redirect implementation.
8. Reuse the existing server-side Login Broker API-key variable and configuration mechanism. If none exists or the key is hardcoded, wire LOGIN_BROKER_API_KEY using only the project's existing configuration pattern and add only a blank/example entry where environment variables are normally documented. Do not introduce a new secret-management approach.
9. Never print, expose, log, hardcode, or commit the API key. In the final report, state whether the variable was already available. If it still needs a value, tell the user to configure LOGIN_BROKER_API_KEY (or the existing variable name) and that the key is available at https://login.broker/settings.
10. Change or remove only code directly superseded by this integration. Run the project's existing relevant checks and any already-existing focused login tests. Do not add new tooling or unrelated tests. Report changed files and checks run.
App — internal window
Add Login Broker social authentication to this app for tenant {tenantName}, using its internal authentication window.
Stay strictly within this integration. Do not refactor unrelated code, redesign the app's authentication or session model, change its configuration strategy, add dependencies unnecessarily, or make product decisions.
1. Locate only the app's existing login action, its existing internal browser/authentication-window component and lifecycle callbacks, and any existing backend login-verification client call or server function available in this project.
2. Login Broker supports these providers, passed as the exact lowercase string in the session URL: google, github, apple, facebook, linkedin, and microsoft. Preserve existing provider choices when they already exist. If the provider is not already specified by the user or existing implementation, ask the user instead of choosing. When adding or updating login buttons, it is a good idea to show each provider's brand icon alongside its label.
3. From the existing explicit login action, as soon as the user taps a provider, replace the login options immediately with a panel that says "Please wait" (or equivalent copy in the app's existing tone) so it is clear authentication has started, then generate a simple GUID as sessionId — do not use crypto, node:crypto, crypto.getRandomValues, or crypto.randomUUID. The sessionId is not a secret and is not sensitive; it only needs to be unique for about 10 minutes, so a trivial GUID or timestamp-plus-random string is enough. Retain it in the app's existing temporary state until verification finishes or fails, and open the app's internal browser/authentication window.
4. Open that internal browser/authentication window at https://social.login.broker/{tenantName}/auth/{provider}/session/{sessionId}. URL-encode the provider and sessionId correctly. Do not add a returnUrl, use provider-specific hosts, or send the API key to this window.
5. While the authentication window is open, poll GET https://social.login.broker/{tenantName}/auth/status/{sessionId} directly from the app every 2 seconds, for at most 60 attempts. This public endpoint needs no API key and returns only the bare status string: pending, completed, or failed. Keep polling while the result is pending. Stop on completed, failed, timeout, or app cancellation.
6. Let Login Broker's successful callback page close the internal window when the app's window component supports JavaScript window.close. The app may also use its existing navigation/content observation capability to close the window after the Login Broker page contains the exact success text “You are now authenticated”. Do not inspect provider credentials, form fields, or unrelated page content, and do not treat window closure, a callback URL, or detected page text as authentication.
7. Treat status polling as independent of the window lifecycle. Whenever the authentication window closes for any reason, do not show the login options again — replace them immediately with a panel that says "Verifying" (or equivalent copy in the app's existing tone) and keep it visible until verification finishes, fails, or times out. Immediately send the retained sessionId to the trusted backend for verification instead of waiting for the next polling interval. If the backend confirms the login, finish immediately. If it responds with 409 or reports that the session is still pending, continue public status polling for the same retained sessionId within the original attempt limit, then verify when completed. A failed status uses the app's existing error path and restores the login options. If polling remains pending through the limit, use its existing timeout or cancellation path and restore the login options.
8. Also send the retained sessionId to the app's existing trusted backend endpoint or server-side function as soon as the public status endpoint returns completed. Accept only the confirmed email returned by that backend, then hand it to the app's existing user/session flow without otherwise changing it and clear the retained session state. Window closure and the public completed status are only triggers for backend verification, not proof of identity. Prevent overlapping verification requests if window closure and a polling response happen at the same time.
9. The API key must never be stored in the app, shipped in its binary, or sent from app code. If this project contains a trusted server function, make it verify GET https://social.login.broker/{tenantName}/auth/result/{sessionId} with X-LoginBroker-ApiKey from its existing server-side configuration and accept only a successful result with status completed, tenantName {tenantName}, and a non-empty email.
10. If no trusted verification endpoint or server-side function is available in this project, do not invent a backend, put the key in the app, or weaken verification. Complete only the safe app-side work, clearly tell the user that the app still needs an endpoint which receives sessionId and returns the confirmed email, and include the following ready-to-copy prompt for the coding agent that has access to their backend:
--- BACKEND AGENT PROMPT ---
Add a server-side Login Broker verification endpoint for tenant {tenantName}.
Stay strictly within this endpoint and its configuration. Follow the backend's existing routing, request-validation, response, error-handling, and configuration conventions. Do not refactor unrelated code, redesign authentication, add features, or introduce new infrastructure or secret-management systems.
1. Add an endpoint using the backend's existing API conventions. It must receive a sessionId from the app and must never receive a Login Broker API key from the app.
2. Validate that sessionId is a non-empty string, then call GET https://social.login.broker/{tenantName}/auth/result/{sessionId} from the server.
3. Read the Login Broker API key from an existing server-side variable. If none exists, wire LOGIN_BROKER_API_KEY through the backend's existing configuration mechanism and add only a blank/example entry where environment variables are normally documented.
4. Send that configured value in the X-LoginBroker-ApiKey header. Never print, expose, log, hardcode, commit, or return the key.
5. Return a confirmed email only when Login Broker responds successfully with status completed, tenantName {tenantName}, and a non-empty email. Otherwise return an error using the backend's existing error format; never accept an email supplied by the app.
6. Keep the endpoint's response limited to what the app needs: the confirmed email and any existing application session result already produced by this backend's login flow. Do not return the Login Broker response or secrets wholesale.
7. Add or update only focused tests in an already-used test framework and run the project's existing relevant checks. Do not add new tooling or unrelated tests.
8. In the final report, state the endpoint URL and expected sessionId request shape. Confirm whether the API-key variable was already configured. If it still needs a value, tell the user exactly which variable to configure and that the key is available at https://login.broker/settings.
--- END BACKEND AGENT PROMPT ---
11. Run the project's existing relevant checks. Add or update only focused tests in an already-used test framework; do not introduce a test framework or unrelated test work. Report changed files, checks run, and whether backend verification remains to be connected.
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());
If you load the script with defer or async
A deferred script has not executed when a framework's mount or hydration hook runs, so window.useLoginBroker may not exist yet. Testing for it there is a race that a fast local machine always wins and production does not — the symptom is a login that works in development and silently does nothing in production.
Wait for the ready event instead. One of the two branches is always true, whichever order the script and your code run in.
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 X-LoginBroker-ApiKey header.
Integrations written before v4 sent the key as Authorization: Secret {yourApiKey}. That form is still accepted, but some hosts — Azure Static Web Apps among them — replace Authorization with a token of their own before your code sees it, which reads here as a wrong key. Use the header above and it cannot happen.
request
GET https://social.login.broker/{tenantName}/auth/result/{sessionId}
X-LoginBroker-ApiKey: {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 https://social.login.broker/{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 https://social.login.broker/{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 https://social.login.broker/{tenantName}/auth/result/{sessionId}
Returns the full session including the verified email. Requires the API key in the X-LoginBroker-ApiKey header. Server-side only.
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 simple GUID as sessionId. It is not a secret — it only needs to be unique for about 10 minutes. Do not use crypto.
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.