Auth Module

The authentication module (sso.auth) handles all authentication flows including OAuth, device flow, token management, and password-based authentication.

OAuth & Login URLs

sso.auth.getLoginUrl()

Signature:

getLoginUrl(provider: OAuthProvider, params: LoginUrlParams): string

Description: Constructs the OAuth login URL for end-users. This does not perform the redirect; the consuming application should redirect the user’s browser to this URL.

Parameters:

Returns: string - The full URL to redirect the user to.

Example:

const url = sso.auth.getLoginUrl('github', {
  org: 'acme-corp',
  service: 'main-app',
  redirect_uri: 'https://app.acme.com/callback'
});
window.location.href = url;

sso.auth.getAdminLoginUrl()

Signature:

getAdminLoginUrl(provider: OAuthProvider, params?: AdminLoginUrlParams): string

Description: Constructs the OAuth login URL for platform/organization admins. This uses the platform’s dedicated OAuth credentials instead of tenant-specific credentials.

Parameters:

Returns: string - The full URL to redirect the admin to.

Example:

const url = sso.auth.getAdminLoginUrl('github', {
  org_slug: 'acme-corp'
});
window.location.href = url;

Device Flow (RFC 8628)

The device flow enables authentication for CLIs, mobile apps, and other devices with limited input capabilities.

sso.auth.deviceCode.request()

Signature:

deviceCode.request(payload: DeviceCodeRequest): Promise<DeviceCodeResponse>

Description: Request a device code for CLI/device authentication. Returns a user code that the user must enter on a separate device.

Parameters:

Returns: Promise<DeviceCodeResponse> - Device code response with user code and verification URI.

Example:

const response = await sso.auth.deviceCode.request({
  client_id: 'service-client-id',
  org: 'acme-corp',
  service: 'acme-cli'
});
console.log(`Visit ${response.verification_uri} and enter code: ${response.user_code}`);

sso.auth.deviceCode.verify()

Signature:

deviceCode.verify(userCode: string): Promise<DeviceVerifyResponse>

Description: Verify a user code and get the context (org_slug, service_slug) needed for the UI to initiate the appropriate OAuth flow. This is called by the web UI when a user enters their device code.

Parameters:

Returns: Promise<DeviceVerifyResponse> - Context with organization and service information.

Example:

const context = await sso.auth.deviceCode.verify('ABCD-1234');
// Use context.org_slug and context.service_slug to determine which OAuth flow to initiate

sso.auth.deviceCode.exchangeToken()

Signature:

deviceCode.exchangeToken(payload: TokenRequest): Promise<TokenResponse>

Description: Exchange a device code for a JWT token. This should be polled by the device/CLI after displaying the user code.

Parameters:

Returns: Promise<TokenResponse> - Token response with JWT access token.

Token Management

sso.auth.logout()

Signature:

logout(): Promise<void>

Description: Logout the current user by revoking their JWT. Automatically clears the session and removes tokens from storage.

sso.auth.refreshToken()

Signature:

refreshToken(refreshToken: string): Promise<RefreshTokenResponse>

Description: Refresh an expired JWT access token using a refresh token. This implements token rotation. The SDK automatically handles token refresh, so you typically don’t need to call this manually.

sso.auth.getProviderToken()

Signature:

getProviderToken(provider: OAuthProvider): Promise<ProviderToken>

Description: Get a fresh provider access token for the authenticated user. This automatically refreshes the token if expired. Requires a service-context JWT.

Parameters:

Returns: Promise<ProviderToken> - Fresh provider token.

Password & MFA

sso.auth.register()

Signature:

register(payload: RegisterRequest): Promise<RegisterResponse>

Description: Register a new user with email and password.

sso.auth.login()

Signature:

login(payload: LoginRequest): Promise<RefreshTokenResponse>

Description: Login with email and password. Automatically persists the session. If MFA is enabled, returns a pre-auth token (short expiry) requiring MFA verification.

sso.auth.verifyMfa()

Signature:

verifyMfa(preauthToken: string, code: string, deviceCodeId?: string): Promise<MfaVerificationResponse>

Description: Verify MFA code and complete authentication. Called after login returns a pre-auth token.

Parameters:

Returns: Promise<MfaVerificationResponse> - Full session tokens.

sso.auth.requestPasswordReset()

Signature:

requestPasswordReset(payload: ForgotPasswordRequest): Promise<ForgotPasswordResponse>

Description: Request a password reset email.

sso.auth.resetPassword()

Signature:

resetPassword(payload: ResetPasswordRequest): Promise<ResetPasswordResponse>

Description: Reset a user’s password using a reset token from email.

sso.auth.verifyEmail()

Signature:

verifyEmail(token: string): Promise<string>

Description: Verify an email address using the token from the verification email.

Parameters:

Returns: Promise<string> - HTML success page string.

Type Definitions

OAuthProvider

type OAuthProvider = 'github' | 'google' | 'microsoft';

LoginUrlParams

interface LoginUrlParams {
  org: string;
  service: string;
  redirect_uri?: string;
  user_code?: string;
}

AdminLoginUrlParams

interface AdminLoginUrlParams {
  org_slug?: string;
  user_code?: string;
}

DeviceCodeRequest

interface DeviceCodeRequest {
  client_id: string;
  org: string;
  service: string;
}

DeviceCodeResponse

interface DeviceCodeResponse {
  device_code: string;
  user_code: string;
  verification_uri: string;
  expires_in: number;
  interval: number;
}

DeviceVerifyResponse

interface DeviceVerifyResponse {
  org_slug: string;
  service_slug: string;
}

TokenRequest

interface TokenRequest {
  grant_type: 'urn:ietf:params:oauth:grant-type:device_code';
  device_code: string;
  client_id: string;
}

TokenResponse

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

RefreshTokenResponse

interface RefreshTokenResponse {
  access_token: string;
  refresh_token: string;
  token_type: string;
  expires_in: number;
}

ProviderToken

interface ProviderToken {
  access_token: string;
  token_type: string;
  scope: string;
  expires_at?: string;
}

RegisterRequest

interface RegisterRequest {
  email: string;
  password: string;
}

RegisterResponse

interface RegisterResponse {
  message: string;
  user_id: string;
}

LoginRequest

interface LoginRequest {
  email: string;
  password: string;
}

ForgotPasswordRequest

interface ForgotPasswordRequest {
  email: string;
}

ForgotPasswordResponse

interface ForgotPasswordResponse {
  message: string;
}

ResetPasswordRequest

interface ResetPasswordRequest {
  token: string;
  new_password: string;
}

ResetPasswordResponse

interface ResetPasswordResponse {
  message: string;
}

MfaVerificationResponse

interface MfaVerificationResponse {
  access_token: string;
  refresh_token: string;
  token_type: string;
  expires_in: number;
}