@xinosolutions/auth-sdk

Sign in with XS Auth — like Google or Microsoft, one button and you get the user back.

About XinoSolutions

XinoSolutions is a software development company dedicated to creating high-quality, developer-friendly solutions. We build modern tools and components that help teams ship secure, polished products faster.

@xinosolutions/auth-sdk is part of our open-source initiative to make XS Auth easy to integrate into any web application.

Add Login with XS next to Google and Microsoft. Call loginWithXS with your clientId and get the signed-in user back.

Browser-only. Requires window, sessionStorage, and crypto. Does not run in Node.js.

Why use this package

• One line to sign in — loginWithXS({ clientId: 'xs_your_app' })
• User profile included — email, firstName, lastName
• Popup login — users stay on your page
• Typed errors — popup blocked, cancelled, timeout, denied

Installation

npm install @xinosolutions/auth-sdk

yarn add @xinosolutions/auth-sdk

pnpm add @xinosolutions/auth-sdk

Before you start

Get your clientId from Xino Solutions (e.g. xs_your_app).

Register allowed domains for every URL where your app runs (http://localhost:3000, https://app.example.com, etc.).

Usage

import { loginWithXS, PopupBlockedError } from '@xinosolutions/auth-sdk';

async function signInWithXS() {
  try {
    const { user, idToken } = await loginWithXS({
      clientId: 'xs_your_app',
    });

    console.log(user.email, user.firstName, user.lastName);

    await fetch('/api/auth/session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include',
      body: JSON.stringify({ idToken }),
    });
  } catch (e) {
    if (e instanceof PopupBlockedError) {
      alert('Please allow popups for this site.');
    }
  }
}

Result shape

{
  "user": {
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "idToken": "eyJhbGciOiJSUzI1NiIs..."
}

• user — display in your UI immediately
• idToken — send to your backend to create a session

Handle errors

import {
  loginWithXS,
  PopupBlockedError,
  PopupClosedError,
  LoginTimeoutError,
  XSAuthDeniedError,
} from '@xinosolutions/auth-sdk';

try {
  const { user, idToken } = await loginWithXS({ clientId: 'xs_your_app' });
} catch (e) {
  if (e instanceof PopupBlockedError) { /* allow popups */ }
  else if (e instanceof PopupClosedError) { /* user cancelled */ }
  else if (e instanceof LoginTimeoutError) { /* retry */ }
  else if (e instanceof XSAuthDeniedError) { /* e.errorCode, e.description */ }
}

React example

import { useState } from 'react';
import { loginWithXS, PopupBlockedError } from '@xinosolutions/auth-sdk';

export function LoginWithXSButton() {
  const [user, setUser] = useState(null);

  async function handleSignIn() {
    try {
      const result = await loginWithXS({ clientId: 'xs_your_app' });
      setUser(result.user);
      await fetch('/api/auth/session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        credentials: 'include',
        body: JSON.stringify({ idToken: result.idToken }),
      });
    } catch (e) {
      if (e instanceof PopupBlockedError) alert('Allow popups and try again.');
    }
  }

  return (
    <>
      <button type="button" onClick={handleSignIn}>
        Login with XS
      </button>
      {user ? <p>Signed in as {user.email}</p> : null}
    </>
  );
}

API reference

loginWithXS(options)

| Option | Type | Default | Description | |---|---|---|---| | clientId | string | — | Your public client id | | parentOrigin | string | window.location.origin | Must be on your allowed domains list | | timeoutMs | number | 120000 | Max wait for login (ms) | | scope | string | — | Optional scope | | useNonce | boolean | false | Optional nonce for backend session setup |

Returns: Promise<{ user: XSAuthUser; idToken: string }>

Error classes

| Error | When | |---|---| | PopupBlockedError | Popup blocked | | PopupClosedError | User closed popup | | LoginTimeoutError | Timed out | | XSAuthDeniedError | Sign-in denied |

Tips

• Trigger login from a button click (popup blockers).
• Register all domains (local + production) as allowed domains.

Troubleshooting

| Symptom | What to check | |---|---| | Popup blocked | User gesture + allow popups | | Domain / origin error | URL not on allowed domains list | | Times out | Increase timeoutMs or try again |

License

MIT

Support

For clientId, allowed domains, or integration help, contact Xino Solutions.