Web Integration Guide — Sign in with Suloro for Websites & Web Apps

Quickstart Overview

Suloro provides a seamless, zero-friction authentication flow for the web. Users can authenticate using a lightweight popup or full redirect, granting your app access to verified profile claims without manual scope configuration.

Developer Console

Zero-Config Parameters

Unlike legacy authentication systems that require declaring long comma-separated permission strings (e.g. scope=name,email,gender,dob), Suloro uses an automated Zero-Config Model.

You only need to pass 2 essential parameters in your authentication request:

Parameter	Type	Description	Example Value
`client_id`	String (Required)	Your registered application Client ID from the Developer Console.	`app_98f412a8bc93...`
`redirect_uri`	String (Required)	The callback URL on your domain that receives the authentication response.	`https://example.com/popup-callback.html`

Based on the permissions configured for your client in the Developer Console, the authenticated payload will automatically include verified user claims: uid, name, email, gender, dateOfBirth, age, photoUrl, and accessToken.

1. Popup Login Flow (Recommended)

The Popup flow opens a centered 500x650 authentication window over your web page. When the user signs in or chooses an account, the popup sends a secure postMessage to your parent window and closes itself automatically.

Complete Frontend Implementation (`index.html`)

HTML & JavaScript (Popup Mode)

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Application - Suloro Login</title>
</head>
<body>

  <!-- Official Sign In with Suloro Button -->
  <button type="button" class="suloro-btn suloro-btn-blue suloro-btn-md suloro-btn-pill" onclick="loginWithSuloroPopup()">
    <img src="https://suloro.com/images/favicon.svg" alt="Suloro" class="suloro-btn-logo" width="22" height="22">
    <span>Sign in with Suloro</span>
  </button>

  <!-- Authenticated User Profile Display UI -->
  <div id="user-profile" style="display: none; margin-top: 20px; padding: 20px; border: 1px solid #e2e8f0; border-radius: 12px;">
    <img id="user-avatar" src="" width="72" height="72" style="border-radius: 50%;" alt="User Avatar">
    <h3 style="margin-top: 10px;">Welcome, <span id="user-name"></span>!</h3>
    <p>Email: <strong id="user-email"></strong></p>
    <p>Gender: <span id="user-gender"></span></p>
    <button type="button" onclick="logoutUser()" style="margin-top: 10px; padding: 8px 16px; cursor: pointer;">Sign Out</button>
  </div>

  <script>
  function loginWithSuloroPopup() {
    const CLIENT_ID = "YOUR_WEB_CLIENT_ID";
    const REDIRECT_URI = window.location.origin + "/popup-callback.html";

    // Center 500x650 Popup Window
    const width = 500, height = 650;
    const left = window.screenX + (window.outerWidth - width) / 2;
    const top = window.screenY + (window.outerHeight - height) / 2;

    const authUrl = `https://accounts.suloro.com/signin?client_id=${encodeURIComponent(CLIENT_ID)}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`;

    const popup = window.open(authUrl, "SuloroAuth", `width=${width},height=${height},top=${top},left=${left}`);

    // Listen for postMessage from popup-callback.html
    const messageHandler = (event) => {
      if (event.origin !== window.location.origin) return;

      if (event.data && event.data.type === "SULORO_AUTH_SUCCESS") {
        window.removeEventListener("message", messageHandler);

        const user = event.data.payload.user;
        const token = event.data.payload.token;

        localStorage.setItem("suloro_token", token);
        localStorage.setItem("suloro_user", JSON.stringify(user));

        renderUserProfile(user);
      }
    };

    window.addEventListener("message", messageHandler);
  }

  function renderUserProfile(user) {
    document.getElementById("user-name").textContent = user.name || "User";
    document.getElementById("user-email").textContent = user.email || "";
    document.getElementById("user-gender").textContent = user.gender || "Not specified";
    document.getElementById("user-avatar").src = user.photoUrl || "https://suloro.com/images/favicon.svg";
    document.getElementById("user-profile").style.display = "block";
  }

  function logoutUser() {
    localStorage.removeItem("suloro_token");
    localStorage.removeItem("suloro_user");
    document.getElementById("user-profile").style.display = "none";
  }
  </script>
</body>
</html>

2. Popup Callback Template (`popup-callback.html`)

Place this lightweight callback file on your web server at the path registered in your redirect_uri (for example: /popup-callback.html).

popup-callback.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Authenticating with Suloro...</title>
</head>
<body>
  <script>
    (function() {
      try {
        const params = new URLSearchParams(window.location.search);
        const hashParams = new URLSearchParams(window.location.hash.substring(1));
        
        const payloadStr = params.get('payload') || hashParams.get('payload');
        if (payloadStr) {
          const payload = JSON.parse(payloadStr);
          if (window.opener) {
            window.opener.postMessage({
              type: "SULORO_AUTH_SUCCESS",
              payload: payload
            }, window.location.origin);
          }
        }
      } catch (err) {
        console.error("Suloro Auth Callback Error:", err);
      } finally {
        window.close();
      }
    })();
  </script>
</body>
</html>

3. Full Redirect Mode

If your web application prefers a standard full-page redirect flow instead of a popup window:

Full Redirect Flow

// 1. Trigger Full Redirect
function loginWithSuloroRedirect() {
  const CLIENT_ID = "YOUR_WEB_CLIENT_ID";
  const REDIRECT_URI = "https://yourwebsite.com/auth/callback";

  window.location.href = `https://accounts.suloro.com/signin?client_id=${encodeURIComponent(CLIENT_ID)}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`;
}

// 2. Handle Callback on /auth/callback
function handleAuthCallback() {
  const params = new URLSearchParams(window.location.search);
  const payloadStr = params.get('payload');

  if (payloadStr) {
    const payload = JSON.parse(payloadStr);
    console.log("Logged In User:", payload.user);
    localStorage.setItem("suloro_token", payload.token);
    window.location.href = "/dashboard";
  }
}

4. Silent Auto-Login (`check_session` via Hidden Iframe)

Silently check whether the user has an active session in Suloro Accounts without prompting them:

Silent Session Check

function checkSuloroSession(callback) {
  const CLIENT_ID = "YOUR_WEB_CLIENT_ID";
  const REDIRECT_URI = window.location.origin + "/silent-callback.html";

  const iframe = document.createElement("iframe");
  iframe.style.display = "none";
  iframe.src = `https://accounts.suloro.com/?action=check_session&client_id=${encodeURIComponent(CLIENT_ID)}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`;

  const messageHandler = (event) => {
    if (event.origin !== window.location.origin) return;

    if (event.data && event.data.type === "SULORO_SESSION_RESULT") {
      window.removeEventListener("message", messageHandler);
      document.body.removeChild(iframe);

      if (event.data.status === "authenticated") {
        callback(true, event.data.user, event.data.token);
      } else {
        callback(false, null, null);
      }
    }
  };

  window.addEventListener("message", messageHandler);
  document.body.appendChild(iframe);
}

5. Account Chooser (Switch Account)

Navigate users to the Suloro Account Chooser for instant 1-click multi-account switching:

Account Chooser Navigation

function switchSuloroAccount() {
  const CLIENT_ID = "YOUR_WEB_CLIENT_ID";
  const REDIRECT_URI = window.location.origin + "/popup-callback.html";

  const width = 500, height = 650;
  const left = window.screenX + (window.outerWidth - width) / 2;
  const top = window.screenY + (window.outerHeight - height) / 2;

  const authUrl = `https://accounts.suloro.com/accountchooser?client_id=${encodeURIComponent(CLIENT_ID)}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`;
  window.open(authUrl, "SuloroAuth", `width=${width},height=${height},top=${top},left=${left}`);
}

6. Sign Out / Logout Flow

Sign Out Flow

function signoutFromSuloro() {
  localStorage.removeItem("suloro_token");
  localStorage.removeItem("suloro_user");

  const REDIRECT_URI = window.location.origin;
  window.location.href = `https://accounts.suloro.com/signin?action=logout&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`;
}

7. Error Codes & Troubleshooting

Error Code	Reason	Resolution
`UNTRUSTED_CLIENT`	Client ID does not exist or has been disabled.	Verify your Client ID in the Suloro Developer Console.
`REDIRECT_URI_MISMATCH`	The requested callback URI is not in your registered list.	Add the callback URL to Registered Callback URIs in the Console.
`CROSS_PLATFORM_MISMATCH`	A Web Client ID was used in an Android app, or vice versa.	Ensure you use the correct platform-specific client credentials.
`UNVERIFIED_APP`	Application review is pending and user rejected prompt.	Submit your app for verification in the Developer Console.
`USER_CANCELLED`	User closed the popup or pressed back without signing in.	Handle gracefully by keeping the login button visible.