API Reference - Core

new AlienSsoClient(config: AlienSsoClientConfig)

const client = new AlienSsoClient({
  ssoBaseUrl: 'https://sso.alien-api.com',
  providerAddress: 'your-provider-address',
  pollingInterval: 5000
});

async generateDeeplink(): Promise<AuthorizeResponse>

GET /oauth/authorize?response_type=code&response_mode=json&client_id={providerAddress}&scope=openid&code_challenge={challenge}&code_challenge_method=S256

{
  deep_link: string;      // Deep link for QR code or mobile redirect
  polling_code: string;   // Code for polling authentication status
  expired_at: number;     // Unix timestamp when session expires
}

const { deep_link, polling_code, expired_at } = await client.generateDeeplink();
console.log('Deep link:', deep_link);
console.log('Expires:', new Date(expired_at * 1000));

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

POST /oauth/poll
Content-Type: application/json
Body: { "polling_code": "..." }

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

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

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Body: grant_type=authorization_code&code={code}&client_id={providerAddress}&code_verifier={verifier}

{
  access_token: string;   // JWT access token
  id_token: string;       // JWT ID token with user claims
  refresh_token: string;  // Opaque refresh token
  token_type: string;     // "Bearer"
  expires_in: number;     // Token lifetime in seconds
}

async verifyAuth(): Promise<UserInfoResponse | null>

GET /oauth/userinfo
Authorization: Bearer {access_token}

{
  sub: string;  // User identifier (session address)
}

async refreshAccessToken(): Promise<TokenResponse>

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Body: grant_type=refresh_token&refresh_token={token}&client_id={providerAddress}

async withAutoRefresh<T>(
  requestFn: () => Promise<T>,
  maxRetries?: number
): Promise<T>

const data = await client.withAutoRefresh(async () => {
  const res = await fetch('/api/data', {
    headers: { Authorization: `Bearer ${client.getAccessToken()}` }
  });
  if (res.status === 401) {
    throw Object.assign(new Error('Unauthorized'), { response: { status: 401 } });
  }
  return res.json();
});

logout(): void

getAccessToken(): string | null

getIdToken(): string | null

getRefreshToken(): string | null

hasRefreshToken(): boolean

getAuthData(): TokenInfo | null

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

getSubject(): string | null

isTokenExpired(): boolean

isAccessTokenExpired(): boolean

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

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

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

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

interface UserInfoResponse {
  sub: string;
}

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

try {
  await client.generateDeeplink();
} catch (error) {
  // Network error, invalid provider, or server error
}
 
try {
  await client.exchangeToken(code);
} catch (error) {
  // Invalid code, expired code, or PKCE mismatch
}
 
try {
  await client.refreshAccessToken();
} catch (error) {
  // Refresh token expired or revoked
  // Client automatically calls logout()
}