Password Reset & Change

OrbNET gives users three complementary ways to manage their credentials: a passwordless forgot-password flow that emails a one-time reset link, a token-based reset-password endpoint that consumes that link, and an authenticated change-password endpoint for users who are already signed in. Mobile apps get dedicated deep-link redirects so a tapped email link opens straight into the OrbVPN app.

Anti-Enumeration by Design

The forgot-password endpoint always returns success, whether or not the email belongs to a real account. This prevents attackers from probing which addresses are registered. If the address exists, a reset email is dispatched; if it does not, nothing happens — but the response is identical either way.

Request a Reset Link

POST/api/v1/auth/forgot-password

Send a password reset link to the email address on file. Always returns success to prevent account enumeration.

Authentication:No Auth Required

Request Parameters

Parameter	Type	Required	Description
`email`	string	Required	The email address associated with the account. Trimmed and lowercased server-side before lookup.
`source`	string	Optional	Where the request originated. One of: mobile, web. When set to "mobile", the reset link points at the app deep-link redirect (/api/v1/auth/reset-password/mobile) so the email opens the OrbVPN app. Defaults to the web reset page.

Code Examples

curl -X POST https://api.orbai.world/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
        "email": "user@example.com",
        "source": "mobile"
    }'

Response

200Request accepted. A reset email is sent only if the account exists. The response is identical in both cases.

{
  "success": true,
  "data": {
    "message": "If an account with that email exists, a password reset link has been sent."
  }
}

422Validation error. The email is missing or malformed.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "details": {
      "email": "Must be a valid email address."
    }
  }
}

Reset the Password

POST/api/v1/auth/reset-password

Consume a one-time reset token from the email link and set a new password.

Authentication:No Auth Required

Request Parameters

Parameter	Type	Required	Description
`token`	string	Required	The one-time reset token delivered in the password reset email. Single-use and time-limited.
`new_password`	string	Required	The new password. Must be between 8 and 100 characters.

Code Examples

curl -X POST https://api.orbai.world/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
        "token": "rst_7f3c9a1e2b8d...",
        "new_password": "MyN3wStr0ngP@ss"
    }'

Responses

200Password reset successfully. The user can now sign in with the new password. A security notification is sent to the account.

{
  "success": true,
  "data": {
    "success": true,
    "message": "Password has been reset successfully. Please login with your new password."
  }
}

400The reset token is invalid, expired, or already used.

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "This password reset link is invalid, expired, or has already been used. Please request a new one."
  }
}

422Validation error. The new password does not meet length requirements.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "details": {
      "new_password": "Must be between 8 and 100 characters."
    }
  }
}

Security Notifications

A successful reset triggers a security notification to the account owner across every enabled channel (push, email, in-app). If a user receives a "Password Reset Successful" alert they did not initiate, it is a signal that their email may be compromised.

Change Password While Signed In

POST/api/v1/auth/change-password

Change the password for the currently authenticated user. Requires the existing password for verification.

Authentication:Bearer Token

Request Parameters

Parameter	Type	Required	Description
`old_password`	string	Required	The user's current password, used to verify identity before the change is applied.
`new_password`	string	Required	The new password. Must be between 8 and 100 characters.

Code Examples

curl -X POST https://api.orbai.world/api/v1/auth/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
        "old_password": "MyCurrentP@ss",
        "new_password": "MyN3wStr0ngP@ss"
    }'

Responses

200Password changed successfully. Returns the number of other device sessions that were revoked as part of the change. A security notification is sent to the account.

{
  "success": true,
  "data": {
    "success": true,
    "devices_logged_out": 2
  }
}

401The current password is incorrect, or the access token is missing or invalid.

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "The current password you entered is incorrect."
  }
}

Sessions Are Cleaned Up

Changing your password returns a devices_logged_out count. Use it in your UI to reassure the user, for example "Your password was changed and 2 other sessions were signed out for security."

Mobile Deep-Link Redirects

When a user taps a reset link in an email on a phone, OrbNET serves a smart redirect page that opens the OrbVPN app directly instead of a web form. These endpoints are reached by the email link itself — your client code never calls them directly.

GET/api/v1/auth/reset-password/mobile

Opened by the password-reset email link on mobile. Validates the token and redirects into the OrbVPN app via a deep link, falling back to a friendly HTML page if the app is not installed.

Authentication:No Auth Required

Parameter	Type	Required	Description
`token`	string	Required	The one-time reset token, supplied as a query string parameter (?token=...). Validated for existence and expiry, then forwarded into the app deep link.

How the Redirect Works

The endpoint validates that the token exists and has not expired, then returns an HTML page that attempts to launch orbvpn:// with the token. If the app is installed, the OrbVPN reset screen opens pre-filled. If it is not, the page shows guidance to install the app or continue on the web. Invalid or expired tokens render a styled error page rather than raw JSON.

A parallel redirect exists for passwordless sign-in: see the Magic Link page for GET /api/v1/auth/magic-link/mobile.

Login -- Email/password authentication
Magic Link -- Passwordless email sign-in
Device Management -- List and revoke active sessions
Two-Factor Authentication -- TOTP and recovery codes

Password Reset & Change