Password Reset

Nexus GSLB supports self-service password reset via email for local accounts. Administrators can also generate reset tokens directly from the CLI without requiring email.

OIDC/SSO accounts cannot use this flow — password management is delegated to the identity provider.

Self-service reset (WebUI)

1. Go to the login page and click Forgot password? beneath the password field.
2. Enter your email address and click Send reset token.
3. Check your inbox for a message from Nexus GSLB containing a one-time reset token.
4. Back on the login page, click I have a token, enter the token and your new password, then click Set new password.

The token expires in 15 minutes. Each request invalidates any previous token for that account.

SMTP not configured

If your administrator has not configured SMTP, the "Send reset token" step returns an error. Ask your administrator to use the gslbctl users reset-password command to generate a token for you.

Admin reset (gslbctl)

Administrators can generate a reset token for any user without needing email to be configured:

gslbctl users reset-password user@example.com --server https://nexus-api.example.com

Output when SMTP is configured:

  Reset token for user@example.com:

    a1b2c3d4e5f6...

  Expires: 2026-06-08 14:30:00
  Email sent to user.

Output when SMTP is not configured:

  Reset token for user@example.com:

    a1b2c3d4e5f6...

  Expires: 2026-06-08 14:30:00
  SMTP not configured — share this token with the user directly.
  They can enter it at the login page under "Forgot password?".

Share the token with the user via a secure channel (encrypted message, password manager, etc.).

API

Request reset email

POST /api/v1/auth/password-reset/request
Content-Type: application/json

{ "email": "user@example.com" }

No authentication required. Always returns 200 to prevent account enumeration. Returns 503 if SMTP is not configured.

Confirm reset

POST /api/v1/auth/password-reset/confirm
Content-Type: application/json

{ "token": "a1b2c3...", "password": "newpassword123" }

No authentication required. Returns 204 on success.

Admin-generate token

POST /api/v1/users/{id}/password-reset
Authorization: Bearer <admin-token>

Requires users:write permission. Returns:

{
  "token": "a1b2c3...",
  "expiresAt": 1749388800,
  "emailSent": true
}

emailSent is false when SMTP is not configured — the token is still valid and can be shared manually.

SMTP configuration

Password-reset emails use the first SMTP entry from your gslbd.yaml alerts.smtp block:

alerts:
  smtp:
    - host: smtp.example.com
      port: 587
      from: "nexus@example.com"
      username: "nexus@example.com"
      password: "..."
      startTls: true

The to field is not required for the reset flow — the destination is always the user's registered email address.

Security notes

• Tokens are single-use and expire after 15 minutes.
• Requesting a reset invalidates any previously issued token for that account.
• The request endpoint always returns 200 to prevent user enumeration.
• Tokens are 32 random bytes (64 hex characters), cryptographically generated.