Forgot Password

Request a password reset email for a user who has forgotten their password.

Request

POST /api/v1/auth/forgot-password

Authentication

Public - No authentication required.

Request Body

{
  "organizationSlug": "acme-corporation",
  "email": "[email protected]"
}

Name	Type	Required	Description
organizationSlug	string	Yes	URL-friendly organization identifier
email	string	Yes	Email address of the user requesting password reset

Response

Success Response (204 No Content)

The endpoint returns a 204 No Content status with no response body, regardless of whether the email/organization combination exists.

Security Design - Silent Failure

For security reasons, this endpoint does not reveal whether the email address or organization exists in the system:

• If the email and organization are valid, a password reset email is sent
• If the email or organization is invalid, no email is sent
• In both cases, the API returns 204 No Content

This prevents attackers from using this endpoint to enumerate valid email addresses or organization names.

Password Reset Email

If the user exists, they will receive an email containing:

• A password reset link with a one-time token
• Token expiration time (typically 1 hour)
• Instructions to reset their password

The reset link will be in the format:

https://app.entryguard.io/reset-password?token={resetToken}

Error Responses

Status Code	Description
400 Bad Request	Invalid request body (missing required fields or invalid email format)
429 Too Many Requests	Rate limit exceeded (prevents abuse of email sending)
500 Internal Server Error	Server error occurred

Example

curl -X POST https://api.entryguard.io/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "organizationSlug": "acme-corporation",
    "email": "[email protected]"
  }'

Example Response

HTTP/1.1 204 No Content

No response body is returned.

Usage Notes

Rate Limiting

This endpoint is rate-limited more aggressively than other endpoints to prevent abuse:

• Per-IP rate limit: Typically 5 requests per 15 minutes
• Per-email rate limit: Typically 3 requests per hour

Exceeding these limits will result in a 429 Too Many Requests error.

Email Delivery

• Password reset emails are sent asynchronously
• The user should receive the email within a few minutes
• If the email doesn't arrive, check spam/junk folders
• Users can request another reset email after the rate limit period

Token Expiration

• Reset tokens typically expire after 1 hour
• Tokens are single-use and invalidated after being used
• If a token expires or is used, the user must request a new one

Suspended Accounts

• If a user account is suspended, no reset email is sent
• If an organization is suspended, no reset email is sent
• The API still returns 204 No Content (silent failure)

Password Reset Flow

1. User requests password reset via this endpoint
2. User receives email with reset link containing token
3. User clicks link and is directed to password reset form
4. User submits new password with token to Reset Password endpoint
5. User is authenticated and can use the new password

Example Frontend Implementation

// JavaScript example
async function requestPasswordReset(organizationSlug, email) {
  try {
    const response = await fetch('https://api.entryguard.io/api/v1/auth/forgot-password', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        organizationSlug,
        email
      })
    });

    if (response.status === 204) {
      // Always show success message (even if email doesn't exist)
      alert('If an account exists with that email, you will receive a password reset link.');
      return true;
    } else if (response.status === 429) {
      alert('Too many requests. Please try again later.');
      return false;
    } else {
      alert('An error occurred. Please try again.');
      return false;
    }
  } catch (error) {
    console.error('Password reset request error:', error);
    alert('An error occurred. Please try again.');
    return false;
  }
}

Related Endpoints

• Reset Password - Complete the password reset with the token from the email
• Change Password - Change password when already authenticated