User Module

The user module (sso.user) manages the authenticated user’s profile, linked social accounts (identities), multi-factor authentication, and password management.

Profile Management

Method: sso.user.getProfile()

Signature:

getProfile(): Promise<UserProfile>

Description: Get the profile of the currently authenticated user. The response includes context from the JWT (org, service).

Parameters: None

Returns: Promise<UserProfile> - User profile with context

Response Fields:

Example:

const profile = await sso.user.getProfile();
console.log(profile.email, profile.org, profile.service);

Throws:

• SsoApiError - When user is not authenticated

Related:

• Update Profile

Method: sso.user.updateProfile()

Signature:

updateProfile(payload: UpdateUserProfilePayload): Promise<UserProfile>

Description: Update the authenticated user’s profile information.

Parameters:

Returns: Promise<UserProfile> - Updated user profile

Example:

const updated = await sso.user.updateProfile({
  email: 'newemail@example.com'
});
console.log('Email updated to:', updated.email);

Throws:

• SsoApiError -
  • When user is not authenticated
  • When email is already in use
  • When email format is invalid

Related:

• Get Profile

Method: sso.user.getSubscription()

Signature:

getSubscription(): Promise<Subscription>

Description: Get the current user’s subscription details for the service in their JWT context.

Parameters: None

Returns: Promise<Subscription> - Subscription details

Response Fields:

Example:

const subscription = await sso.user.getSubscription();
console.log(subscription.plan, subscription.features);
if (subscription.features.includes('premium-support')) {
  // Enable premium support features
}

Throws:

• SsoApiError -
  • When user is not authenticated
  • When user has no subscription

Related:

• Service Plans

Password Management

Method: sso.user.changePassword()

Signature:

changePassword(payload: ChangePasswordRequest): Promise<ChangePasswordResponse>

Description: Change the authenticated user’s password. Requires the current password for verification. This is for users who already have a password set.

Parameters:

Returns: Promise<ChangePasswordResponse> - Confirmation message

Response Fields:

Example:

const response = await sso.user.changePassword({
  current_password: 'OldPassword123!',
  new_password: 'NewSecurePassword456!'
});
console.log(response.message); // "Password changed successfully"

Throws:

• SsoApiError -
  • When user is not authenticated
  • When current password is incorrect
  • When new password doesn’t meet requirements
  • When new password is same as current password

Related:

• Set Password
• Password Requirements Guide

Method: sso.user.setPassword()

Signature:

setPassword(payload: SetPasswordRequest): Promise<SetPasswordResponse>

Description: Set a password for the authenticated user (OAuth users only). This endpoint is for OAuth users who don’t have a password yet and want to add password login capability. If a password is already set, this will return an error.

Parameters:

Returns: Promise<SetPasswordResponse> - Confirmation message

Response Fields:

Example:

const response = await sso.user.setPassword({
  new_password: 'MyNewSecurePassword123!'
});
console.log(response.message); // "Password set successfully"

Throws:

• SsoApiError -
  • When user is not authenticated
  • When user already has a password set
  • When password doesn’t meet requirements

Related:

• Change Password
• Password Requirements Guide

Identities Module

The identities module (sso.user.identities) manages social account linking for the authenticated user.

Method: sso.user.identities.list()

Signature:

identities.list(): Promise<Identity[]>

Description: List all social accounts linked to the authenticated user.

Parameters: None

Returns: Promise<Identity[]> - Array of linked identities

Response Fields (per Identity):

Example:

const identities = await sso.user.identities.list();
console.log(identities); // [{ provider: 'github' }, { provider: 'google' }]
identities.forEach(id => {
  console.log(`Linked: ${id.provider} (${id.email})`);
});

Throws:

• SsoApiError - When user is not authenticated

Related:

• Start Link
• Unlink Identity

Method: sso.user.identities.startLink()

Signature:

identities.startLink(provider: string): Promise<StartLinkResponse>

Description: Start linking a new social account to the authenticated user. Returns an authorization URL that the user should be redirected to complete the OAuth flow.

Parameters:

Returns: Promise<StartLinkResponse> - Object containing the authorization URL

Response Fields:

Example:

const { authorization_url } = await sso.user.identities.startLink('github');
window.location.href = authorization_url; // Redirect user to complete OAuth

Throws:

• SsoApiError -
  • When user is not authenticated
  • When identity is already linked
  • When provider is invalid

Related:

• List Identities
• Unlink Identity

Method: sso.user.identities.unlink()

Signature:

identities.unlink(provider: string): Promise<void>

Description: Unlink a social account from the authenticated user. Note: Cannot unlink the last remaining identity to prevent account lockout.

Parameters:

Returns: Promise<void>

Example:

await sso.user.identities.unlink('google');
console.log('Google account unlinked successfully');

Throws:

• SsoApiError -
  • When user is not authenticated
  • When trying to unlink the last remaining identity
  • When identity is not linked
  • When provider is invalid

Related:

• List Identities
• Start Link

MFA Module

The MFA module (sso.user.mfa) manages multi-factor authentication (TOTP) for the authenticated user.

Method: sso.user.mfa.getStatus()

Signature:

mfa.getStatus(): Promise<MfaStatusResponse>

Description: Get the current MFA status for the authenticated user.

Parameters: None

Returns: Promise<MfaStatusResponse> - MFA status

Response Fields:

Example:

const status = await sso.user.mfa.getStatus();
console.log(status.enabled); // false
if (status.enabled && status.backup_codes_remaining < 3) {
  console.warn('Running low on backup codes - consider regenerating');
}

Throws:

• SsoApiError - When user is not authenticated

Related:

• MFA Setup
• MFA Disable

Method: sso.user.mfa.setup()

Signature:

mfa.setup(): Promise<MfaSetupResponse>

Description: Initiate MFA setup. Generates a TOTP secret and QR code. The user must complete setup by calling verify() with a code from their authenticator app.

Parameters: None

Returns: Promise<MfaSetupResponse> - MFA setup details including QR code

Response Fields:

Example:

const setup = await sso.user.mfa.setup();
console.log(setup.qr_code_svg); // Display this QR code to the user
// User scans QR code with authenticator app (Google Authenticator, Authy, etc.)
// Then calls verify() with the code from their app

Throws:

• SsoApiError -
  • When user is not authenticated
  • When MFA is already enabled

Related:

• MFA Verify
• MFA Guide

Method: sso.user.mfa.verify()

Signature:

mfa.verify(code: string): Promise<MfaVerifyResponse>

Description: Verify TOTP code and enable MFA. Returns backup codes that must be stored securely by the user. These codes can be used for account recovery if the user loses access to their authenticator app.

Parameters:

Returns: Promise<MfaVerifyResponse> - Verification response with backup codes

Response Fields:

Example:

const result = await sso.user.mfa.verify('123456');
console.log(result.backup_codes); // Store these securely!

// Display backup codes to user
alert(`
  MFA Enabled Successfully!

  IMPORTANT: Save these backup codes in a secure location.
  Each code can only be used once.

  ${result.backup_codes.join('\n')}
`);

Throws:

• SsoApiError -
  • When user is not authenticated
  • When TOTP code is incorrect
  • When MFA is already enabled
  • When MFA setup was not initiated

Related:

• MFA Setup
• Regenerate Backup Codes

Method: sso.user.mfa.disable()

Signature:

mfa.disable(): Promise<{ success: boolean; message: string }>

Description: Disable MFA for the authenticated user. This will delete the TOTP secret and all backup codes.

Parameters: None

Returns: Promise<{ success: boolean; message: string }> - Confirmation response

Example:

await sso.user.mfa.disable();
console.log('MFA disabled successfully');

Throws:

• SsoApiError -
  • When user is not authenticated
  • When MFA is not enabled

Related:

• MFA Setup
• MFA Status

Method: sso.user.mfa.regenerateBackupCodes()

Signature:

mfa.regenerateBackupCodes(): Promise<BackupCodesResponse>

Description: Regenerate backup codes. Invalidates all previous backup codes and returns new ones. Use this when running low on backup codes or if codes may have been compromised.

Parameters: None

Returns: Promise<BackupCodesResponse> - New backup codes

Response Fields:

Example:

const { backup_codes } = await sso.user.mfa.regenerateBackupCodes();
console.log(backup_codes); // Store these securely!

// All previous backup codes are now invalid
alert(`
  New Backup Codes Generated

  Previous codes are no longer valid.
  Save these new codes in a secure location.

  ${backup_codes.join('\n')}
`);

Throws:

• SsoApiError -
  • When user is not authenticated
  • When MFA is not enabled

Related:

• MFA Verify
• MFA Status

Type Definitions

UserProfile

interface UserProfile {
  id: string;
  email: string;
  email_verified: boolean;
  created_at: string;
  org?: string;
  service?: string;
  role?: string;
}

UpdateUserProfilePayload

interface UpdateUserProfilePayload {
  email?: string;
}

Subscription

interface Subscription {
  id: string;
  user_id: string;
  plan_id: string;
  plan_name: string;
  status: 'active' | 'cancelled' | 'expired';
  features: string[];
  current_period_start: string;
  current_period_end: string;
  created_at: string;
}

Identity

interface Identity {
  provider: string;
  provider_user_id: string;
  email?: string;
  created_at: string;
}

StartLinkResponse

interface StartLinkResponse {
  authorization_url: string;
}

ChangePasswordRequest

interface ChangePasswordRequest {
  current_password: string;
  new_password: string;
}

ChangePasswordResponse

interface ChangePasswordResponse {
  message: string;
}

SetPasswordRequest

interface SetPasswordRequest {
  new_password: string;
}

SetPasswordResponse

interface SetPasswordResponse {
  message: string;
}

MfaStatusResponse

interface MfaStatusResponse {
  enabled: boolean;
  backup_codes_remaining?: number;
}

MfaSetupResponse

interface MfaSetupResponse {
  secret: string;
  qr_code_svg: string;
  issuer: string;
  account_name: string;
}

MfaVerifyResponse

interface MfaVerifyResponse {
  success: boolean;
  message: string;
  backup_codes: string[];
}

BackupCodesResponse

interface BackupCodesResponse {
  backup_codes: string[];
}