Skip to Content
⚠️ Note: Some details in this documentation may not be fully accurate yet.
API ReferenceReact

API Reference - React

Complete API documentation for @alien_org/sso-sdk-react.

AlienSsoProvider

Context provider component that wraps your application and provides authentication state.

Props

interface AlienSsoProviderProps {
  config: AlienSsoClientConfig;
  children: React.ReactNode;
}

Configuration:

ParameterTypeRequiredDescription
ssoBaseUrlstringYesBase URL of the SSO service
providerAddressstringYesYour provider address
pollingIntervalnumberNoPolling interval in ms (default: 5000)

Example:

import { AlienSsoProvider } from '@alien_org/sso-sdk-react';
 
function App() {
  return (
    <AlienSsoProvider
      config={{
        ssoBaseUrl: 'https://sso.alien-api.com',
        providerAddress: 'your-provider-address',
        pollingInterval: 5000
      }}
    >
      <YourApp />
    </AlienSsoProvider>
  );
}

useAuth Hook

Hook that provides access to authentication state and methods. Must be used within AlienSsoProvider.

function useAuth(): UseAuthReturn

Return Value

interface UseAuthReturn {
  client: AlienSsoClient;
  auth: AuthState;
  queryClient: QueryClient;
  generateDeeplink: () => Promise<AuthorizeResponse>;
  pollAuth: (pollingCode: string) => Promise<PollResponse>;
  exchangeToken: (authCode: string) => Promise<TokenResponse>;
  verifyAuth: () => Promise<boolean>;
  refreshToken: () => Promise<boolean>;
  logout: () => void;
  openModal: () => void;
  closeModal: () => void;
  isModalOpen: boolean;
}

Properties

client

Direct access to the AlienSsoClient instance.

const { client } = useAuth();
const token = client.getAccessToken();

auth

Current authentication state.

interface AuthState {
  isAuthenticated: boolean;
  token: string | null;
  tokenInfo: TokenInfo | null;
}

TokenInfo (OIDC standard claims):

interface TokenInfo {
  iss: string;               // Issuer URL
  sub: string;               // Subject (user identifier)
  aud: string | string[];    // Audience (provider address)
  exp: number;               // Expiration timestamp
  iat: number;               // Issued at timestamp
  nonce?: string;            // Nonce if provided
  auth_time?: number;        // Authentication time
}

Example:

const { auth } = useAuth();
 
if (auth.isAuthenticated) {
  console.log('User ID:', auth.tokenInfo?.sub);
  console.log('Token:', auth.token);
  console.log('Expires:', new Date(auth.tokenInfo!.exp * 1000));
}

queryClient

React Query client instance for advanced usage.

const { queryClient } = useAuth();
queryClient.invalidateQueries(['some-key']);

Methods

Generates authentication deep link and polling code.

async generateDeeplink(): Promise<AuthorizeResponse>

Returns:

{
  deep_link: string;      // URL for QR code or redirect
  polling_code: string;   // Code for polling status
  expired_at: number;     // Unix timestamp
}

pollAuth()

Polls for authentication status.

async pollAuth(pollingCode: string): Promise<PollResponse>

Returns:

{
  status: 'pending' | 'authorized' | 'rejected' | 'expired';
  authorization_code?: string;  // Only when status is 'authorized'
}

exchangeToken()

Exchanges authorization code for tokens. Updates auth state on success.

async exchangeToken(authCode: string): Promise<TokenResponse>

Returns:

{
  access_token: string;
  id_token: string;
  refresh_token: string;
  token_type: string;
  expires_in: number;
}

Side Effects:

  • Updates auth state with new tokens
  • Stores tokens in localStorage

verifyAuth()

Verifies current access token by calling /oauth/userinfo.

async verifyAuth(): Promise<boolean>

Returns: true if token is valid, false otherwise.

Side Effects:

  • Updates auth state based on verification result
  • Automatically refreshes token on 401 (via underlying client)

refreshToken()

Refreshes the access token using the stored refresh token.

async refreshToken(): Promise<boolean>

Returns: true if refresh succeeded, false if failed.

Side Effects:

  • Updates auth state with new tokens on success
  • Clears auth state and calls logout on failure

Example:

const { refreshToken, auth } = useAuth();
 
// Proactive refresh before token expires
if (auth.tokenInfo && auth.tokenInfo.exp * 1000 < Date.now() + 60000) {
  const success = await refreshToken();
  if (!success) {
    // Redirect to login
  }
}

logout()

Clears authentication state and storage.

logout(): void

Side Effects:

  • Updates auth state to unauthenticated
  • Removes all tokens from localStorage
  • Removes code verifier from sessionStorage

openModal() / closeModal()

Control the built-in sign-in modal.

openModal(): void
closeModal(): void

Example:

const { openModal, closeModal, isModalOpen } = useAuth();
 
<button onClick={openModal}>Sign In</button>
{isModalOpen && <button onClick={closeModal}>Cancel</button>}

isModalOpen

Boolean indicating if the sign-in modal is currently open.

Components

SignInButton

Pre-styled button component that opens the sign-in modal.

function SignInButton(): JSX.Element

Example:

import { SignInButton } from '@alien_org/sso-sdk-react';
 
function LoginPage() {
  return (
    <div>
      <h1>Welcome</h1>
      <SignInButton />
    </div>
  );
}

SignInModal

Modal component for the authentication flow. Automatically rendered by AlienSsoProvider.

This component:

  • Displays QR code with deep link
  • Handles polling automatically
  • Shows loading and error states
  • Exchanges token on successful authentication
  • Updates auth state when complete

Controlling the modal:

const { openModal, closeModal } = useAuth();
 
openModal();  // Open modal
closeModal(); // Close modal

Types

AlienSsoClientConfig

interface AlienSsoClientConfig {
  ssoBaseUrl: string;
  providerAddress: string;
  pollingInterval?: number;
}

AuthState

interface AuthState {
  isAuthenticated: boolean;
  token: string | null;
  tokenInfo: TokenInfo | null;
}

TokenInfo

interface TokenInfo {
  iss: string;
  sub: string;
  aud: string | string[];
  exp: number;
  iat: number;
  nonce?: string;
  auth_time?: number;
}

AuthorizeResponse

interface AuthorizeResponse {
  deep_link: string;
  polling_code: string;
  expired_at: number;
}

PollResponse

interface PollResponse {
  status: 'pending' | 'authorized' | 'rejected' | 'expired';
  authorization_code?: string;
}

TokenResponse

interface TokenResponse {
  access_token: string;
  id_token: string;
  refresh_token: string;
  token_type: string;
  expires_in: number;
}

Usage Examples

Basic Authentication

import { AlienSsoProvider, useAuth, SignInButton } from '@alien_org/sso-sdk-react';
 
function App() {
  return (
    <AlienSsoProvider
      config={{
        ssoBaseUrl: 'https://sso.alien-api.com',
        providerAddress: 'your-provider-address',
      }}
    >
      <Dashboard />
    </AlienSsoProvider>
  );
}
 
function Dashboard() {
  const { auth, logout } = useAuth();
 
  if (!auth.isAuthenticated) {
    return <SignInButton />;
  }
 
  return (
    <div>
      <p>Welcome! User ID: {auth.tokenInfo?.sub}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

Protected Route

import { useAuth } from '@alien_org/sso-sdk-react';
import { Navigate } from 'react-router-dom';
 
function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { auth } = useAuth();
 
  if (!auth.isAuthenticated) {
    return <Navigate to="/login" replace />;
  }
 
  return <>{children}</>;
}

Token Refresh on API Calls

import { useAuth } from '@alien_org/sso-sdk-react';
 
function useApi() {
  const { auth, refreshToken, logout } = useAuth();
 
  async function fetchWithAuth(url: string) {
    // Check if token is expiring within 1 minute
    if (auth.tokenInfo && auth.tokenInfo.exp * 1000 < Date.now() + 60000) {
      const success = await refreshToken();
      if (!success) {
        logout();
        throw new Error('Session expired');
      }
    }
 
    return fetch(url, {
      headers: {
        Authorization: `Bearer ${auth.token}`
      }
    });
  }
 
  return { fetchWithAuth };
}

Custom Sign-In Flow

import { useAuth } from '@alien_org/sso-sdk-react';
import { useState, useEffect } from 'react';
 
function CustomSignIn() {
  const { generateDeeplink, pollAuth, exchangeToken, auth } = useAuth();
  const [deepLink, setDeepLink] = useState<string | null>(null);
  const [pollingCode, setPollingCode] = useState<string | null>(null);
 
  const handleSignIn = async () => {
    const response = await generateDeeplink();
    setDeepLink(response.deep_link);
    setPollingCode(response.polling_code);
  };
 
  useEffect(() => {
    if (!pollingCode) return;
 
    const interval = setInterval(async () => {
      const response = await pollAuth(pollingCode);
 
      if (response.status === 'authorized') {
        clearInterval(interval);
        await exchangeToken(response.authorization_code!);
        setDeepLink(null);
        setPollingCode(null);
      } else if (response.status === 'rejected' || response.status === 'expired') {
        clearInterval(interval);
        setDeepLink(null);
        setPollingCode(null);
      }
    }, 5000);
 
    return () => clearInterval(interval);
  }, [pollingCode]);
 
  if (deepLink) {
    return <QRCode value={deepLink} />;
  }
 
  return <button onClick={handleSignIn}>Sign In</button>;
}

Token Verification on Mount

import { useAuth } from '@alien_org/sso-sdk-react';
import { useEffect } from 'react';
 
function App() {
  const { verifyAuth, auth } = useAuth();
 
  useEffect(() => {
    if (auth.token) {
      verifyAuth();
    }
  }, []);
 
  // Rest of your app
}

Error Handling

All async methods can throw errors. Handle them appropriately:

const { generateDeeplink, exchangeToken, refreshToken } = useAuth();
 
try {
  const { deep_link, polling_code } = await generateDeeplink();
} catch (error) {
  console.error('Failed to generate deep link:', error);
}
 
try {
  await exchangeToken(authCode);
} catch (error) {
  console.error('Token exchange failed:', error);
}
 
try {
  const success = await refreshToken();
  if (!success) {
    // Handle refresh failure (user logged out automatically)
  }
} catch (error) {
  console.error('Refresh error:', error);
}

Next Steps

Last updated on
CoreDemo App