Reset Password

Complete the password reset process using a token received via email.

Request

POST /api/v1/auth/reset-password

Authentication

Public - No authentication required (token is provided in request body).

Request Body

{
  "token": "reset_pwd_abc123xyz789...",
  "password": "NewSecurePass456!"
}

Name	Type	Required	Description
token	string	Yes	Password reset token received via email (from forgot-password flow)
password	string	Yes	New password (8-128 characters, must comply with organization password policy)

Response

Success Response (200 OK)

Upon successful password reset, the user is automatically authenticated and receives tokens (same as login response):

{
  "mfaRequired": false,
  "mfaChallengeToken": null,
  "mfaChallengeExpiresIn": null,
  "passwordExpired": false,
  "passwordChangeToken": null,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "expiresIn": 3600,
  "tokenType": "Bearer",
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "[email protected]",
    "name": "John Doe",
    "isOrgAdmin": true,
    "organizationId": "223e4567-e89b-12d3-a456-426614174001",
    "organizationName": "Acme Corporation",
    "organizationSlug": "acme-corporation",
    "subscriptionTier": "BUSINESS",
    "mfaEnabled": false
  }
}

Response Fields

Field	Type	Description
mfaRequired	boolean	Whether MFA verification is required (typically false for password reset)
mfaChallengeToken	string	Token for MFA verification (null if MFA not required)
mfaChallengeExpiresIn	number	MFA challenge expiration in seconds (null if MFA not required)
passwordExpired	boolean	Whether password is expired (always false after reset)
passwordChangeToken	string	Token for password change (null after reset)
accessToken	string	JWT access token for authenticated requests
refreshToken	string	Refresh token to obtain new access tokens
expiresIn	number	Access token expiration time in seconds
tokenType	string	Token type (always "Bearer")
user	object	User information object

Password Policy Validation

The new password must comply with the organization's password policy. Common requirements include:

• Minimum length: 8 characters
• Maximum length: 128 characters
• May require uppercase letters
• May require lowercase letters
• May require numbers
• May require special characters
• May prevent reuse of recent passwords

Error Responses

Status Code	Description
400 Bad Request	Invalid request body (missing required fields)
401 Unauthorized	Invalid, expired, or already-used reset token
403 Forbidden	User or organization is suspended
422 Unprocessable Entity	New password fails organization password policy validation
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error occurred

Password Policy Error Response

{
  "error": "Password does not meet policy requirements",
  "details": {
    "minLength": 8,
    "maxLength": 128,
    "requireUppercase": true,
    "requireLowercase": true,
    "requireNumbers": true,
    "requireSpecialChars": true,
    "preventReuse": 5,
    "violations": [
      "Password must contain at least one uppercase letter",
      "Password must contain at least one special character"
    ]
  }
}

Example

curl -X POST https://app.entryguard.io/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset_pwd_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a",
    "password": "NewSecurePass456!"
  }'

Example Response (Success)

{
  "mfaRequired": false,
  "mfaChallengeToken": null,
  "mfaChallengeExpiresIn": null,
  "passwordExpired": false,
  "passwordChangeToken": null,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJvcmdJZCI6IjIyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMSIsInJvbGVzIjpbIk9SR19BRE1JTiJdLCJpYXQiOjE3MDkwNDk2MDAsImV4cCI6MTcwOTA1MzIwMH0.xyz123",
  "refreshToken": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "expiresIn": 3600,
  "tokenType": "Bearer",
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "[email protected]",
    "name": "John Doe",
    "isOrgAdmin": true,
    "organizationId": "223e4567-e89b-12d3-a456-426614174001",
    "organizationName": "Acme Corporation",
    "organizationSlug": "acme-corporation",
    "subscriptionTier": "BUSINESS",
    "mfaEnabled": false
  }
}

Example Error Response (Invalid Token)

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Invalid or expired reset token"
}

Example Error Response (Policy Violation)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "Password does not meet policy requirements",
  "details": {
    "minLength": 8,
    "requireUppercase": true,
    "requireLowercase": true,
    "requireNumbers": true,
    "requireSpecialChars": true,
    "violations": [
      "Password must contain at least one number"
    ]
  }
}

Usage Notes

Token Lifecycle

• Reset tokens are single-use and invalidated immediately after successful password reset
• Tokens typically expire after 1 hour
• Attempting to reuse a token will result in a 401 Unauthorized error
• If a token expires, the user must request a new one via Forgot Password

Session Management

When a user successfully resets their password:

• All existing refresh tokens for that user are revoked (forced logout from all devices)
• A new access token and refresh token are issued
• The user is immediately authenticated and can access the application

Security Notifications

Best practice is to send an email notification to the user when their password is reset, informing them of the change and advising them to contact support if they didn't initiate the reset.

Frontend Implementation Example

// JavaScript example - parse token from URL and reset password
async function resetPassword() {
  // Extract token from URL query parameter
  const urlParams = new URLSearchParams(window.location.search);
  const token = urlParams.get('token');
  const newPassword = document.getElementById('password').value;

  if (!token) {
    alert('Invalid reset link');
    return;
  }

  try {
    const response = await fetch('https://app.entryguard.io/api/v1/auth/reset-password', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        token,
        password: newPassword
      })
    });

    if (response.ok) {
      const data = await response.json();

      // Store tokens
      localStorage.setItem('accessToken', data.accessToken);
      localStorage.setItem('refreshToken', data.refreshToken);
      localStorage.setItem('user', JSON.stringify(data.user));

      // Redirect to dashboard
      window.location.href = '/dashboard';
    } else if (response.status === 401) {
      alert('Reset link is invalid or expired. Please request a new one.');
    } else if (response.status === 422) {
      const error = await response.json();
      alert(`Password does not meet requirements: ${error.details.violations.join(', ')}`);
    } else {
      alert('An error occurred. Please try again.');
    }
  } catch (error) {
    console.error('Password reset error:', error);
    alert('An error occurred. Please try again.');
  }
}

Related Endpoints

• Forgot Password - Request password reset email
• Change Password - Change password when already authenticated
• Login - Authenticate with email and password