Password Authentication on AuthOS Docs | Auth Operating System API and SDK Guides

Registration

Mon, 01 Jan 0001 00:00:00 +0000

Complete the password authentication prerequisites before registering a user. Registration is the first step in the password authentication sequence.

User Registration

Registration creates a new user account with email and password. Users receive a verification email and must verify their email address before logging in.

Basic Registration

import { SsoClient, SsoApiError } from '@drmhse/sso-sdk';

const sso = new SsoClient({
  baseURL: 'https://sso.example.com'
});

async function registerUser(email: string, password: string) {
  try {
    const response = await sso.auth.register({
      email: email,
      password: password
    });

    console.log(response.message);
    // "Registration successful. Please check your email to verify your account."
    return true;
  } catch (error) {
    if (error instanceof SsoApiError) {
      console.error('Registration failed:', error.message);
      // Handle specific errors (email already exists, weak password, etc.)
    }
    return false;
  }
}

Registration with Organization Context

If your organization has configured custom SMTP settings, include the org_slug to ensure the verification email is sent using your organization’s email configuration:

Email Verification

Mon, 01 Jan 0001 00:00:00 +0000

Start after registering the user. SMTP must be configured as described in the password authentication prerequisites.

Email Verification

After registration, users receive an email with a verification link. The verification is handled automatically by the platform. Once verified, users can log in with their credentials.

Treat verification as a required checkpoint in your application: show the registration success state, direct the user to their inbox, and do not establish a password session until AuthOS accepts the verified account. If login returns HTTP 403, return the user to this checkpoint instead of reporting invalid credentials.

Login and Sessions

Mon, 01 Jan 0001 00:00:00 +0000

Complete Email verification before starting this flow. Accounts with MFA enabled receive a short-lived pre-authentication token before AuthOS establishes the full session.

After email verification, users can authenticate with their email and password.

async function loginWithPassword(email: string, password: string) {
  try {
    // The SDK automatically handles token storage and configuration
    await sso.auth.login({
      email: email,
      password: password
    });

    console.log('Login successful');
    return true;
  } catch (error) {
    if (error instanceof SsoApiError) {
      if (error.statusCode === 401) {
        console.error('Invalid email or password');
      } else if (error.statusCode === 403) {
        console.error('Email not verified. Please check your email.');
      } else {
        console.error('Login failed:', error.message);
      }
    }
    return false;
  }
}

If the user has MFA enabled, the login will return a pre-authentication token instead of a full session token. The full session is only stored after successful MFA verification:

Password Reset

Mon, 01 Jan 0001 00:00:00 +0000

Use this flow when a password user cannot authenticate. It deliberately returns the same request response whether or not the email address belongs to an account.

Password Reset Workflow

The password reset flow consists of three steps:

User requests a password reset
User receives an email with a reset link
User submits a new password with the reset token

Step 1: Request Password Reset

async function requestPasswordReset(email: string) {
  try {
    const response = await sso.auth.requestPasswordReset({
      email: email,
      org_slug: 'acme-corp' // Optional: use org-specific SMTP
    });

    console.log(response.message);
    // "If the email exists, a password reset link has been sent"
    return true;
  } catch (error) {
    console.error('Failed to send reset email:', error);
    return false;
  }
}

Security Note: The API always returns success, even if the email doesn’t exist. This prevents email enumeration attacks.

Account Management

Mon, 01 Jan 0001 00:00:00 +0000

Use these flows after authentication. Existing password users must prove their current password; OAuth-created users can add a password to enable an additional login method.

Change Password (Authenticated Users)

Authenticated users can change their password by providing their current password for verification.

Basic Password Change

async function changePassword(currentPassword: string, newPassword: string) {
  try {
    const response = await sso.user.changePassword({
      current_password: currentPassword,
      new_password: newPassword
    });

    console.log(response.message);
    // "Password changed successfully"
    return true;
  } catch (error) {
    if (error instanceof SsoApiError) {
      if (error.statusCode === 401) {
        console.error('Current password is incorrect');
      } else {
        console.error('Password change failed:', error.message);
      }
    }
    return false;
  }
}

Change Password Form

import { useState } from 'react';
import { SsoClient, SsoApiError } from '@drmhse/sso-sdk';

interface ChangePasswordFormProps {
  sso: SsoClient;
}

export function ChangePasswordForm({ sso }: ChangePasswordFormProps) {
  const [currentPassword, setCurrentPassword] = useState('');
  const [newPassword, setNewPassword] = useState('');
  const [confirmPassword, setConfirmPassword] = useState('');
  const [error, setError] = useState('');
  const [success, setSuccess] = useState(false);
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError('');
    setSuccess(false);

    if (newPassword !== confirmPassword) {
      setError('New passwords do not match');
      return;
    }

    if (newPassword.length < 8) {
      setError('New password must be at least 8 characters');
      return;
    }

    if (newPassword === currentPassword) {
      setError('New password must be different from current password');
      return;
    }

    setLoading(true);

    try {
      await sso.user.changePassword({
        current_password: currentPassword,
        new_password: newPassword
      });

      setSuccess(true);
      // Clear form
      setCurrentPassword('');
      setNewPassword('');
      setConfirmPassword('');
    } catch (err) {
      if (err instanceof SsoApiError) {
        if (err.statusCode === 401) {
          setError('Current password is incorrect');
        } else {
          setError(err.message);
        }
      } else {
        setError('Failed to change password. Please try again.');
      }
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <h2>Change Password</h2>

      <div className="form-group">
        <label htmlFor="currentPassword">Current Password</label>
        <input
          id="currentPassword"
          type="password"
          value={currentPassword}
          onChange={(e) => setCurrentPassword(e.target.value)}
          required
        />
      </div>

      <div className="form-group">
        <label htmlFor="newPassword">New Password</label>
        <input
          id="newPassword"
          type="password"
          value={newPassword}
          onChange={(e) => setNewPassword(e.target.value)}
          required
          placeholder="At least 8 characters"
        />
      </div>

      <div className="form-group">
        <label htmlFor="confirmPassword">Confirm New Password</label>
        <input
          id="confirmPassword"
          type="password"
          value={confirmPassword}
          onChange={(e) => setConfirmPassword(e.target.value)}
          required
        />
      </div>

      {error && <div className="error">{error}</div>}
      {success && (
        <div className="success">Password changed successfully!</div>
      )}

      <button type="submit" disabled={loading}>
        {loading ? 'Changing Password...' : 'Change Password'}
      </button>
    </form>
  );
}

Set Password for OAuth Users

Users who originally signed up via OAuth (GitHub, Google, Microsoft) don’t have a password. They can set a password to enable password-based login.

Troubleshooting and Security

Mon, 01 Jan 0001 00:00:00 +0000

Use this guide to harden the complete password authentication sequence and map SDK failures to safe, actionable messages.

Best Practices

Password Security

Client-Side Validation: Validate password strength before submission
Never Log Passwords: Never log passwords in plain text
HTTPS Only: Always use HTTPS in production
Rate Limiting: The platform implements rate limiting on auth endpoints
Secure Storage: Never store passwords in browser storage

Password Strength Requirements

Implement client-side validation to provide immediate feedback:

Password Authentication on AuthOS Docs | Auth Operating System API and SDK Guides

Registration

User Registration

Basic Registration

Registration with Organization Context

Email Verification

Email Verification

Login and Sessions

Login with Email and Password

Basic Login

Login with MFA Support

Password Reset

Password Reset Workflow

Step 1: Request Password Reset

Account Management

Change Password (Authenticated Users)

Basic Password Change

Change Password Form

Set Password for OAuth Users

Troubleshooting and Security

Best Practices

Password Security

Password Strength Requirements