Reset Password

Resets a user's password using a two-step process: challenge (OTP generation) and confirm (password update). This endpoint uses OTP (One-Time Password) sent via email to verify the user's identity before allowing password reset.

Endpoint

POST /auth/reset-password

Authentication: Tenant authentication required

Description

The reset-password endpoint allows users to reset their password through a secure two-step process using the OTP (One-Time Password) module. For detailed information about OTP operations, see OTP Overview.

1. Challenge step: The user provides their email address. If the email exists in the system, an OTP is generated and sent to the user's email. The OTP information is returned in the response. After receiving the OTP, the user must verify it before proceeding to the confirm step.
2. Confirm step: The user provides the OTP token (received from the challenge step) and the new password. The OTP is consumed and the password is updated.

This two-step process ensures that only users with access to the registered email address can reset their password.

Important: Only users who registered with the password method can use this endpoint. Users with other authentication methods (Social providers, OTP, guest) do not have passwords to reset.

Request

The request body structure depends on the step being performed.

Challenge Step

{
  "step": "challenge",
  "email": "user@example.com"
}

Parameter	Type	Required	Description	Constraints
step	string	Yes	Reset password step	Must be "challenge"
email	string	Yes	User's email address	Valid email format

Confirm Step

{
  "step": "confirm",
  "token": "otp-token-id",
  "password": "newsecurepassword123"
}

Parameter	Type	Required	Description	Constraints
step	string	Yes	Reset password step	Must be "confirm"
token	string	Yes	OTP token ID from challenge step	Non-empty string
password	string	Yes	New password	Minimum 8 characters

Response

Status Code: 201 Created

Challenge Step Response

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "data": {
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "expiresAt": "2025-01-15T10:35:00.000Z",
    "resendIntervalSeconds": 60
  }
}

Field	Type	Description
id	string	OTP token ID (use in confirm step)
createdAt	string	ISO 8601 creation timestamp
expiresAt	string	ISO 8601 expiration timestamp
resendIntervalSeconds	number	Resend interval in seconds

Confirm Step Response

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "data": {
    "success": true
  }
}

Field	Type	Description
success	boolean	Always true on success

Rate Limiting

Rate limiting is applied to prevent abuse and ensure system stability. The reset-password endpoint has the following rate limits:

Limit Type	Rate	Window
Per IP	10 requests	1 hour

When rate limits are exceeded, the API returns a 429 Too Many Requests status code.

For information about rate limit headers, see Rate Limiting in the overview.

Errors

For detailed explanations of all error codes, see the Error Codes page where you can find all system errors.

400 Bad Request - Validation Error

Occurs when the request body fails validation. Common causes include invalid email format, password too short, missing required fields, or invalid step value.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "The provided request data is invalid.",
    "code": "VALIDATION_ERROR",
    "status": 400,
    "validation": {
      "step": "Invalid enum value",
      "email": "Invalid email",
      "password": "String must contain at least 8 character(s)"
    }
  }
}

Field	Error Message	Cause
step	Invalid enum value	Step is not "challenge" or "confirm"
email	Invalid email	Email format is invalid (challenge step)
token	Required	Token is missing (confirm step)
password	String must contain at least 8 character(s)	Password is less than 8 characters (confirm step)

403 Forbidden - Restricted Capability

Occurs when the reset-password capability is restricted for the tenant.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Capability reset-password is restricted",
    "code": "RESTRICTED_CAPABILITY",
    "status": 403
  }
}

409 Conflict - Reset Password User Not Found

Occurs during the challenge step when no user with the provided email address exists in the system.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Reset password user not found.",
    "code": "RESET_PASSWORD_USER_NOT_FOUND",
    "status": 409
  }
}

429 Too Many Requests - Rate Limit Exceeded

Occurs when the rate limit is exceeded. See Rate Limiting section for details.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Too many requests",
    "code": "TOO_MANY_REQUESTS",
    "status": 429
  }
}

500 Internal Server Error

Occurs when an internal error happens during password reset. Common causes include missing email/token/password, invalid step, missing scope ID, or other unexpected system state.

Error codes:

• UNEXPECTED_STATE - Unexpected system state (e.g., missing email/token/password, invalid step, missing scope ID)
• INTERNAL_SERVER - General internal server error

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Missing email address for password reset.",
    "code": "UNEXPECTED_STATE",
    "status": 500
  }
}

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Something went wrong on our side.",
    "code": "INTERNAL_SERVER",
    "status": 500
  }
}

OTP Errors

The following errors can occur during the confirm step when consuming the OTP:

404 Not Found - OTP Not Found

Occurs when the OTP token provided in the confirm step does not exist or has expired.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP not found",
    "code": "OTP_NOT_FOUND",
    "status": 404
  }
}

422 Unprocessable Entity - OTP Not Consumable

Occurs when the OTP cannot be consumed. This includes cases where the OTP has already been consumed or is in an invalid state.

Error codes:

• OTP_NOT_CONSUMABLE - OTP is not in a consumable state
• OTP_ALREADY_CONSUMED - OTP has already been consumed

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP is not consumable",
    "code": "OTP_NOT_CONSUMABLE",
    "status": 422
  }
}

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP has already been consumed",
    "code": "OTP_ALREADY_CONSUMED",
    "status": 422
  }
}

500 Internal Server Error - OTP Consume Callback Error

Occurs when an error happens during the OTP consume callback (password update operation).

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP consume callback error",
    "code": "OTP_CONSUME_CALLBACK_ERROR",
    "status": 500
  }
}

Notes

• The reset-password endpoint uses a two-step process: challenge (OTP generation) and confirm (password update)
• Only users who registered with the password authentication method can reset their password