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:
| Name | Type | Description |
|---|---|---|
| provider | OAuthProvider | The OAuth provider to use (‘github’, ‘google’, ‘microsoft’) |
| params | LoginUrlParams | Login parameters including org, service, and redirect_uri |
| params.org | string | Organization slug |
| params.service | string | Service slug |
| params.redirect_uri | string (optional) | Callback URL after authentication |
| params.user_code | string (optional) | Device flow user code to link browser session to device |
| params.connection_id | string (optional) | Enterprise IdP connection ID for HRD-routed login |
Returns: string - The full URL to redirect the user to.
sso.auth.getAdminLoginUrl()
Signature:
getAdminLoginUrl(provider: OAuthProvider, params?: AdminLoginUrlParams): string
Description: Constructs the OAuth login URL for platform/organization admins.
Device Flow (RFC 8628)
sso.auth.deviceCode.request() | verify() | exchangeToken()
Standard RFC 8628 device authorization flow methods. exchangeToken should be polled by the device/CLI.
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. 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 (e.g., to call GitHub API).
Password & MFA
sso.auth.register()
Signature:
register(payload: RegisterRequest): Promise<RegisterResponse>
Description: Register a new user with email and password.
sso.auth.resendVerification()
Signature:
resendVerification(payload: ResendVerificationRequest): Promise<ResendVerificationResponse>
Description: Resend the verification email to a user. Returns success regardless of whether the email exists to prevent enumeration.
sso.auth.verifyEmail()
Signature:
verifyEmail(token: string): Promise<string>
Description: Verify an email address using the token from the verification email. Returns the success HTML page.
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 (expires_in: 300) requiring MFA verification.
sso.auth.verifyMfa()
Signature:
verifyMfa(preauthToken: string, code: string, deviceCodeId?: string): Promise<MfaVerificationResponse>
Description: Verify MFA code (TOTP or backup code) and complete authentication. Automatically persists the session.
sso.auth.requestPasswordReset() | resetPassword()
Standard forgot/reset password flow methods.
Home Realm Discovery (HRD)
sso.auth.lookupEmail()
Signature:
lookupEmail(email: string): Promise<LookupEmailResponse>
Description: Lookup an email address to determine the correct authentication method (Enterprise IdP, Password, or Social).
Example:
const result = await sso.auth.lookupEmail('john@acmecorp.com');
if (result.auth_method === 'upstream' && result.connection_id) {
// Route to enterprise IdP
const url = sso.auth.getLoginUrl('github', {
org: 'acme-corp',
service: 'main-app',
connection_id: result.connection_id
});
window.location.href = url;
}
Type Definitions
Refer to sso-sdk/src/types for complete interface definitions of payloads and responses.