Password Management

Manage user passwords and email verification. These endpoints cover the complete password lifecycle: requesting a reset, resetting with a token, changing a known password, and verifying email addresses.

The forgot password and reset password endpoints are public and do not reveal whether an email address exists in the system. This prevents user enumeration attacks.

POST/auth/api/v1/auth/forgot-password

Request password reset

Request a password reset email. If the provided email address is associated with an account, a reset link will be sent. The response is always the same regardless of whether the account exists, to prevent user enumeration.

The reset link contains a one-time token that expires after a configurable duration (default: 60 minutes).

Required attributes

Name
login
Type
string
Description
The email address of the account to reset.

Request

POST

/auth/api/v1/auth/forgot-password

curl -X POST https://your-sphere.example.com/auth/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"login": "user@example.com"}'

Response

{
  "message": "If the account exists, a reset link has been sent."
}

POST/auth/api/v1/auth/reset-password

Reset password

Reset a user's password using the token received via the password reset email. The token is single-use and expires after a limited time. After a successful reset, all existing sessions for the user are revoked.

Required attributes

Name
token
Type
string
Description
The one-time reset token from the password reset email.
Name
login
Type
string
Description
The email address of the account being reset. Must match the account the token was generated for.
Name
password
Type
string
Description
The new password. Must meet the password policy requirements (see auth config).
Name
password_confirmation
Type
string
Description
Confirmation of the new password. Must match the password field exactly.

Request

POST

/auth/api/v1/auth/reset-password

curl -X POST https://your-sphere.example.com/auth/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "login": "user@example.com",
    "password": "NewSecurePass456!",
    "password_confirmation": "NewSecurePass456!"
  }'

Response

{
  "message": "Password has been reset successfully."
}

POST/auth/api/v1/auth/change-password

Change password

Change the authenticated user's password. Requires the current password for verification. After a successful change, all other sessions for the user are revoked (the current session remains active).

Required attributes

Name
current_password
Type
string
Description
The user's current password for verification.
Name
password
Type
string
Description
The new password. Must meet the password policy requirements.
Name
password_confirmation
Type
string
Description
Confirmation of the new password. Must match the password field exactly.

Request

POST

/auth/api/v1/auth/change-password

curl -X POST https://your-sphere.example.com/auth/api/v1/auth/change-password \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "SecurePass123!",
    "password": "NewSecurePass456!",
    "password_confirmation": "NewSecurePass456!"
  }'

Response

{
  "message": "Password has been changed successfully."
}

POST/auth/api/v1/auth/email/send-verification

Send email verification

Send a verification email to the authenticated user's email address. The email contains a one-time token that must be submitted to the verify endpoint to confirm the email address.

This endpoint requires authentication and accepts no request body.

Request

POST

/auth/api/v1/auth/email/send-verification

curl -X POST https://your-sphere.example.com/auth/api/v1/auth/email/send-verification \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response

{
  "message": "Verification email has been sent."
}

POST/auth/api/v1/auth/email/verify

Verify email

Verify the user's email address using the token received via the verification email. Once verified, the user's email_verified_at timestamp is set and certain features that require a verified email become available.

Required attributes

Name
token
Type
string
Description
The one-time verification token from the email.

Request

POST

/auth/api/v1/auth/email/verify

curl -X POST https://your-sphere.example.com/auth/api/v1/auth/email/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJpdiI6IjEyMzQ1Njc4OTAi..."}'

Response

{
  "message": "Email has been verified successfully.",
  "data": {
    "email_verified_at": "2026-02-24T10:30:00Z"
  }
}