Password Reset Object

The Password Reset Object represents a short-lived session used to reset the password of a partner (root account) or a partner login (sub-login).

A password reset session is created with a POST request and is then advanced step by step with PATCH requests until the new password is set. Each PATCH request must include the confirmation code sent by email; a session that requires MFA also expects a second, separately delivered code.

A session expires 30 minutes after creation, and can be used to set a password only once. Submitting 5 wrong email codes, or 5 wrong MFA codes, cancels the session. Creating a new password reset for the same target cancels any previous active session for that target, so only the code from the most recently sent email works.

How Password Reset Works

Use a password reset when a partner or a partner login (sub-login) forgot its password. For example, your application can offer a Forgot password page: the user enters their login, and your application uses the requests below to let the user set a new password.

The user proves that they own the account with a code that CarrierX sends to the email address of the account. If the partner login has MFA configured, the user must also enter an MFA code.

The process uses two requests:

• Create Password Reset (POST) starts the process. You send it once.
• Advance Password Reset (PATCH) moves the process forward. You send it one or more times, until the new password is set.

Steps

1. Start the reset. Send a Create Password Reset request with the login, partner_sid, or partner_login_sid of the target. CarrierX sends an email with a 6-digit code and a link. The link is base_url followed directly by password_reset_sid, so if you set your own base_url, end it with /. The code is valid for 30 minutes.
2. Collect the code. The user opens the link, and your page reads password_reset_sid from it. The user enters the code from the email.
3. Check the email code. Send an Advance Password Reset request with email_code. The response status shows the next step:
   • ready: the target has no MFA. Go to step 5.
   • mfa_required: CarrierX sent an MFA code to the target. mfa_method and mfa_destination in the response show where it was sent. The destination is masked, for example a***@example.com. Go to step 4.
4. Check the MFA code (only if status is mfa_required). Send email_code and mfa_code. The status becomes ready. The MFA code is valid for 5 minutes. If it expires, repeat step 3 to get a new one.
5. Set the new password. Send email_code and new_password. The status becomes completed, and CarrierX sends a "Your password was changed" email to the target.

Step	Request	Body	Status after the request
1	Create Password Reset	login, partner_sid, or partner_login_sid	pending
3	Advance Password Reset	email_code	ready or mfa_required
4	Advance Password Reset	email_code, mfa_code	ready
5	Advance Password Reset	email_code, new_password	completed

You can combine steps. Without MFA, send email_code and new_password in one request. With MFA, send step 3 first to get the MFA code, then send email_code, mfa_code, and new_password together.

If Something Goes Wrong

• The email did not arrive, or the code expired: send a new Create Password Reset request. The old session is canceled, and only the code from the newest email works.
• The MFA code did not arrive: repeat step 3 with only email_code. The MFA code is sent again, at most once every 60 seconds.
• Too many wrong codes: 5 wrong email codes, or 5 wrong MFA codes, cancel the session. Start again with a new Create Password Reset request.

note

To avoid showing which logins exist, show the same message after every Create Password Reset request, even when it returns an error. For example: "If an account with this login exists, we have sent an email."

Password Reset Object Attributes

The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Attribute	Data Type	Description
password_reset_sid read only	string	The password reset secure ID.
partner_sid create	string	The secure ID of the partner (root account) targeted by the password reset. Exactly one of partner_sid, partner_login_sid, and login must be set to create a password reset.
partner_login_sid create	string	The secure ID of the partner login (sub-login) targeted by the password reset. Exactly one of partner_sid, partner_login_sid, and login must be set to create a password reset.
login create	string	The login targeted by the password reset. May be set instead of partner_sid or partner_login_sid; it is resolved to a partner first, then to a partner login, using the same precedence as authentication. For security reasons this field is returned as null until the emailed email_code has been verified with a PATCH request, even when the reset was originally targeted by login.
status read only	string	The status of the password reset. Values accepted in this field are pending, mfa_required, ready, completed, expired, and canceled. A session is created as pending, moves to mfa_required only if the target has MFA configured, then to ready once the email code (and, when applicable, the MFA code) has been verified, and finally to completed once the new password has been set. expired and canceled are terminal states reached outside of this normal progression: expired after 30 minutes with no completion, canceled after 5 failed code attempts or when a newer password reset is created for the same target.
date_expiry read only	string	The date and time when the password reset expires, 30 minutes after creation.
base_url create	string	The URL prefix used in the emailed password reset link, followed by password_reset_sid. If not specified when creating the password reset, a default value is used.

Sample Password Reset object

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