Advance Password Reset

This request advances a password reset session, targeted by secure ID, by one step. The email_code from the password reset email is required in every request.

For the full process, see How Password Reset Works.

patch

/oauth/password-reset/{password_reset_sid}

Submitting only email_code verifies it and reports the next step in the response status: ready if the target has no MFA configured, or mfa_required if an MFA challenge was just sent. Once the status is ready, submitting new_password (together with the codes already verified) sets the new password and completes the reset. email_code and, when applicable, mfa_code and new_password can also be combined in a single request to skip the intermediate steps.

The response is always an envelope of the shape {item, mfa_required, mfa_method, mfa_destination} — see Response Envelope below.

Sample 1

A sample PATCH request to verify the email code for a target with no MFA configured:

curl -X PATCH \
'https://api.carrierx.com/core/v2/oauth/password-reset/0d6f9a34-52c1-47f8-91be-3fb2a6d0c815' \
-H 'Content-Type: application/json' \
--data-binary '{"email_code":"482913"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 1

200 status code with the operation envelope. The code was correct, so status becomes ready and login is revealed:

{
    "item": {
        "password_reset_sid": "0d6f9a34-52c1-47f8-91be-3fb2a6d0c815",
        "partner_sid": null,
        "partner_login_sid": "b0a1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
        "login": "fcctest_mching_sublogin1",
        "status": "ready",
        "date_expiry": "2026-07-12T13:15:42.000Z",
        "base_url": "https://carrierx.com/new-password/"
    },
    "mfa_required": false
}

Sample 2

A sample PATCH request to complete the reset once status is ready:

curl -X PATCH \
'https://api.carrierx.com/core/v2/oauth/password-reset/0d6f9a34-52c1-47f8-91be-3fb2a6d0c815' \
-H 'Content-Type: application/json' \
--data-binary '{"email_code":"482913","new_password":"N3wPassw0rd!"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 2

200 status code with the operation envelope. The password is set, a "Your password was changed" notification email is sent, and the session becomes terminal:

{
    "item": {
        "password_reset_sid": "0d6f9a34-52c1-47f8-91be-3fb2a6d0c815",
        "partner_sid": null,
        "partner_login_sid": "b0a1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
        "login": "fcctest_mching_sublogin1",
        "status": "completed",
        "date_expiry": "2026-07-12T13:15:42.000Z",
        "base_url": "https://carrierx.com/new-password/"
    },
    "mfa_required": false
}

email_code and new_password can be sent together in the first request for a target with no MFA, completing the reset directly from pending.

Sample 3

A sample PATCH request to verify the email code for a target with MFA configured:

curl -X PATCH \
'https://api.carrierx.com/core/v2/oauth/password-reset/0d6f9a34-52c1-47f8-91be-3fb2a6d0c815' \
-H 'Content-Type: application/json' \
--data-binary '{"email_code":"482913"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 3

200 status code with the operation envelope. The email code was correct; an MFA code was sent to the login's configured MFA destination and status becomes mfa_required:

{
    "item": {
        "password_reset_sid": "0d6f9a34-52c1-47f8-91be-3fb2a6d0c815",
        "partner_sid": null,
        "partner_login_sid": "b0a1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
        "login": "fcctest_mching_sublogin1",
        "status": "mfa_required",
        "date_expiry": "2026-07-12T13:15:42.000Z",
        "base_url": "https://carrierx.com/new-password/"
    },
    "mfa_required": true,
    "mfa_method": "email",
    "mfa_destination": "s***@example.com"
}

Sample 4

A sample PATCH request to verify the MFA code sent in Sample 3:

curl -X PATCH \
'https://api.carrierx.com/core/v2/oauth/password-reset/0d6f9a34-52c1-47f8-91be-3fb2a6d0c815' \
-H 'Content-Type: application/json' \
--data-binary '{"email_code":"482913","mfa_code":"719262"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 4

200 status code with the operation envelope. status becomes ready; complete the reset the same way as in Sample 2:

{
    "item": {
        "password_reset_sid": "0d6f9a34-52c1-47f8-91be-3fb2a6d0c815",
        "partner_sid": null,
        "partner_login_sid": "b0a1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
        "login": "fcctest_mching_sublogin1",
        "status": "ready",
        "date_expiry": "2026-07-12T13:15:42.000Z",
        "base_url": "https://carrierx.com/new-password/"
    },
    "mfa_required": false
}

email_code, mfa_code, and new_password can also be sent together to go directly from mfa_required to completed in one request.

Required Scopes

To advance a Password Reset object, the partner must have one of the following scopes enabled:

oauth.manage
oauth.update

Path Arguments

Parameter	Data Type	Description
password_reset_sid required	string	The password reset secure ID.

Body Arguments

Parameter	Data Type	Description
email_code required	string	The confirmation code emailed when the password reset was created. Required in every request to this endpoint.
mfa_code	string	The MFA code sent to the target once `status` becomes `mfa_required`. Required together with `email_code` while the reset is in the `mfa_required` state.
new_password	string	The new password for the target. Setting this field completes the reset; it is only accepted once the reset has reached (or is reaching, in the same request) the `ready` state.

Response Envelope

Every response from this endpoint has the same shape, regardless of which step was just performed:

Field	Data Type	Description
item read only	object	A serialized copy of the Password Reset object in its state after this request.
mfa_required read only	boolean	Whether an MFA verification step is required to complete the reset.
mfa_method read only	string	The MFA method of the pending challenge. Values accepted in this field are `email`, `sms`, and `totp`. Only present while `mfa_required` is `true`.
mfa_destination read only	string	The masked destination the MFA code was sent to (`null` for the `totp` method). Only present while `mfa_required` is `true`.

Notes

Repeating a request with only email_code while status is mfa_required re-sends the MFA code, throttled to once every 60 seconds. A repeat sent inside the cooldown window returns the current state without re-sending.
A wrong email_code or mfa_code is rejected with a 422 error; the 5th consecutive wrong code (of either kind) cancels the session instead.
A password reset that has expired (30 minutes after creation) or is already completed, canceled, or expired rejects further PATCH requests with a 409 error.
Attempt counters and terminal-state transitions (canceled, expired) are persisted even though the request that triggers them returns an error.
Sending mfa_code against a target that has no MFA configured returns a validation error without affecting the session: the correct email_code can still be resubmitted afterward (without mfa_code) to reach ready normally.

Errors

Situation	Code	Field → Message
Unknown `password_reset_sid`	`404`	"cannot find password reset by sid"
Missing `email_code`	`422`	`email_code` → "empty value"
Wrong `email_code`, attempts 1-4	`422`	`email_code` → "invalid value"
Wrong `email_code`, 5th attempt	`422`	`email_code` → "too many failed attempts; request a new password reset" (session becomes `canceled`)
`new_password` sent while `mfa_required` without `mfa_code`	`422`	`mfa_code` → "empty value" (password unchanged)
Wrong `mfa_code`, attempts 1-4	`422`	`code` → "invalid MFA code"
Wrong `mfa_code`, 5th attempt	`422`	"too many failed attempts; request a new password reset" (session becomes `canceled`)
`mfa_code` sent but target has no MFA configured	`422`	`mfa_code` → "MFA is not configured for this login"
Session older than 30 minutes	`409`	`status` → "password reset has expired; request a new one" (session becomes `expired`)
Session already `completed`, `canceled`, or `expired`	`409`	`status` → "password reset is completed" (or the matching terminal status)

Sample 1​

Response 1​

Sample 2​

Response 2​

Sample 3​

Response 3​

Sample 4​

Response 4​

Required Scopes​

Path Arguments​

Body Arguments​

Response Envelope​

Notes​

Errors​