Request a password reset

POST

/password-resets

Initiates the password-reset flow for an email/password identity. This endpoint is public — it is called before the caller has any session or API credentials, so no Authorization header is required or checked. On success, a single-use password-reset token is generated and an email containing it is queued for delivery to the account's registered address; the raw token itself is never returned in the API response. The response is intentionally minimal ({ "pending": true }) and does not confirm or deny account existence in its message text, though note that an unregistered email currently causes this endpoint to return a distinct 404 rather than the same 200 — treat this as a known enumeration surface rather than an intended contract.

Request

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

The password-reset request was accepted and reset instructions have been queued for delivery to the identity's registered email address.

Bodyapplication/json

🟠400

🟠404

Request Example

Shell

JavaScript

Java

Swift

curl --location '/password-resets' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "jane.doe@acmecorp.ng"
}'

Response Example

200 - Success

{
    "message": "Password reset instructions have been sent to your email",
    "status": "success",
    "data": {
        "pending": true
    }
}

Modified at 2026-09-28 12:45:48

Verify an email address

Complete a password reset with a one-time token