Home Documentation Authentication and User Management Service Integration Guides Password Management

Password Management

Last updated: January 2026

The Agglestone Authentication and User Management Service provides comprehensive password management features, including forgot password functionality, password reset during login, and the ability for users to reset their passwords from within your application.

Password Reset Scenarios

There are three main scenarios where users may need to reset their passwords:

  1. Forgot Password: Users who have forgotten their password can request a reset link via email
  2. Forced Reset During Login: Administrators can require users to reset their password on their next login
  3. User-Initiated Reset: Authenticated users can reset their password from within your application

All password resets enforce your configured password requirements, such as minimum length and character requirements (uppercase, lowercase, numbers, symbols).

Forgot Password Flow

When a user forgets their password, they can request a password reset through the forgot password endpoint. This sends a secure, time-limited reset token to their email address.

Initiating Forgot Password

The Forgot Password link is normally shown on the securely hosted login page on the Agglestone Authentication and User Management Service. When users click this link, the username is sent to the Agglestone Authentication and User Management Service, were a check made to validate the request. The user is then sent a secure, time-limited reset token to their email address. Users click the link in the email to complete the password reset process.

If you have set up a custom HTML page for your login page, then the forgot password link can be removed from the default login page if necessary.

Completing Password Reset

After the user receives the email and clicks the reset link, they’ll be taken to a password reset page, hosted by the Agglestone Authentication and User Management Service, where they can enter their new password. The reset token from the email link is used to validate and complete the reset, and is valid for a maximum of 1 hour to avoid the opportunity for compromise.

The password reset page is hosted by the Agglestone Authentication and User Management Service, but you can customize its appearance with your own HTML and CSS to match your application’s branding.

Password Reset During Login

If a user is required to reset their password during login (configured by an administrator), they’ll be prompted to set a new password during the login flow. This happens automatically after they enter their current valid password but before they can access your application.

The user enters their current password, then is presented with a password reset form where they must enter and confirm their new password. Once the password is reset, they can proceed with the login flow.

User-Initiated Password Reset from Your Application

Authenticated users can reset their password from within your application. This requires two steps:

  1. Get a One-Time Token: Call the one-time token endpoint to get a short-lived reset token (expires in 30 seconds)
  2. Reset Password: Use the token to call the reset password endpoint

Step 1: Get One-Time Token

The one-time token endpoint requires authentication (JWT token) and returns a token that expires in 30 seconds:

// Get one-time token for password reset
public async Task<string> GetOneTimeTokenAsync(string accessToken)
{
    var tenantId = "your-tenant-id";
    var request = new HttpRequestMessage(HttpMethod.Post, 
        $"https://auth.agglestone.com/tenant/{tenantId}/v2.0/Auth/one-time-token");
    request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);  // JWT token required
    
    var response = await httpClient.SendAsync(request);
    response.EnsureSuccessStatusCode();
    
    var result = await response.Content.ReadFromJsonAsync<OneTimeTokenResponse>();
    return result.Token; // Use this token immediately (expires in 30 seconds)
}

// Get one-time token for password reset
async function getOneTimeToken() {
  const tenantId = 'your-tenant-id';
  const response = await fetch(
    `https://auth.agglestone.com/tenant/${tenantId}/v2.0/Auth/one-time-token`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}` // JWT token required
      }
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const result = await response.json();
  return result.token; // Use this token immediately (expires in 30 seconds)
}

# Get one-time token for password reset
async def get_one_time_token():
    tenant_id = "your-tenant-id"
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"https://auth.agglestone.com/tenant/{tenant_id}/v2.0/Auth/one-time-token",
            headers={
                "Authorization": f"Bearer {access_token}"  # JWT token required
            }
        )
        response.raise_for_status()
        result = response.json()
        return result["token"]  # Use this token immediately (expires in 30 seconds)

Step 2: Redirect to Password Reset Page

Once you have the one-time token, redirect the user to the secure password reset page on the Agglestone Authentication and User Management Service by calling the GET reset-password endpoint with the token in the query string:

// Redirect user to password reset page
public void RedirectToPasswordReset(string token)
{
    var tenantId = "your-tenant-id";
    var resetUrl = $"https://auth.agglestone.com/tenant/{tenantId}/v2.0/Auth/reset-password?token={Uri.EscapeDataString(token)}";
    
    // Redirect user's browser to the reset URL
    // In ASP.NET Core: return Redirect(resetUrl);
    // In other contexts: Process.Start(resetUrl) or similar
}

// Redirect user to password reset page
function redirectToPasswordReset(token) {
  const tenantId = 'your-tenant-id';
  const resetUrl = `https://auth.agglestone.com/tenant/${tenantId}/v2.0/Auth/reset-password?token=${encodeURIComponent(token)}`;
  
  // Redirect user's browser to the reset URL
  window.location.href = resetUrl;
}

# Redirect user to password reset page
def redirect_to_password_reset(token):
    tenant_id = "your-tenant-id"
    reset_url = f"https://auth.agglestone.com/tenant/{tenant_id}/v2.0/Auth/reset-password?token={urllib.parse.quote(token)}"
    
    # Redirect user's browser to the reset URL
    # In Flask: return redirect(reset_url)
    # In other frameworks: use appropriate redirect method
    return redirect(reset_url)

The user is then taken to a secure password reset page hosted by the Agglestone Authentication and User Management Service. On this page, they enter their current password, their new password, and confirm their new password. The page is customizable with your own HTML and CSS to match your application’s branding.

Complete Example: User-Initiated Password Reset

Here’s a complete example showing both steps together:

// Complete password reset flow from within your app
async function resetPasswordFromApp() {
  const tenantId = 'your-tenant-id';
  const accessToken = userManager.getUser()?.access_token; // Get from your auth library
  
  // Step 1: Get one-time token
  const tokenResponse = await fetch(
    `https://auth.agglestone.com/tenant/${tenantId}/v2.0/Auth/one-time-token`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );
  
  const tokenData = await tokenResponse.json();
  const resetToken = tokenData.token; // Expires in 30 seconds - use immediately!
  
  // Step 2: Redirect user to password reset page
  const resetUrl = `https://auth.agglestone.com/tenant/${tenantId}/v2.0/Auth/reset-password?token=${encodeURIComponent(resetToken)}`;
  window.location.href = resetUrl;
  
  // User will enter current password, new password, and confirm password on the hosted page
}

Password Requirements

All password resets enforce your configured password requirements:

  • Minimum password length – Configurable minimum length (default: 8 characters)
  • Character requirements – Optionally require uppercase letters, lowercase letters, numbers, and/or symbols

These requirements are enforced consistently across all password reset scenarios, ensuring all users have strong passwords that meet your security standards.

Password Configuration

Administrators can configure password settings per tenant:

  • Password Attempt Limits: Configure the maximum number of failed password attempts before lockout
  • Lockout Period: Set how long users must wait after reaching the attempt limit before trying again

These settings allow you to balance security with user experience, ensuring strong protection against brute force attacks without being overly restrictive.

> 📚 API Documentation: For detailed API documentation, request/response schemas, and to try out the endpoints interactively, visit the Swagger UI.

—

Ready to learn more? Check out the Login and Logout Guide to understand the authentication flow, or learn about Multi-Factor Authentication for enhanced security.