Device Management & Sessions

Every OrbVPN subscription allows a fixed number of simultaneous devices. OrbNET tracks each signed-in device as a session and exposes a small set of endpoints so users can see exactly what is connected, remotely sign out a lost or unknown device, and free up a slot when they hit their plan's device limit during login. This page also covers two adjacent session utilities: refreshing JWT claims after a subscription change, and verifying a user's email.

Device-Aware Sessions

A "device" here is a logged-in session keyed by a device_id your client supplies at login. Listing, naming, and revoking devices all operate on that identifier. Revoking a device immediately invalidates its tokens and pushes a force-logout notification to that device over WebSocket and FCM.

List Active Devices

GET/api/v1/auth/devices

Return all active device sessions for the authenticated user, the device making the request, and the plan's device allowance.

Authentication:Bearer Token

Code Examples

curl https://api.orbai.world/api/v1/auth/devices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response

200The list of active devices, the count currently in use, and the plan's maximum. The device making the request is flagged with is_current: true.

{
  "success": true,
  "data": {
    "devices": [
      {
        "device_id": "550e8400-e29b-41d4-a716-446655440000",
        "device_name": "iPhone 15 Pro",
        "platform": "ios",
        "app_version": "3.4.0",
        "login_date": "2026-06-20T08:14:00Z",
        "last_active": "2026-06-26T11:02:00Z",
        "is_current": true
      },
      {
        "device_id": "9b2f7c10-44ad-4f0e-bb71-2c0f8e91d3aa",
        "device_name": "Pixel 8 Pro",
        "platform": "android",
        "app_version": "3.4.0",
        "login_date": "2026-06-18T19:40:00Z",
        "last_active": "2026-06-25T07:55:00Z",
        "is_current": false
      }
    ],
    "current_devices": 2,
    "max_devices": 5
  }
}

Field Notes

current_devices is the number of active sessions; max_devices is the limit granted by the user's subscription plan (it varies per plan and defaults to 1 when no plan is found). device_name, platform, and app_version come from the values your client sent at login.

Sign Out a Specific Device

POST/api/v1/auth/logout-device

Remotely sign out one device by its device_id. The target device receives an immediate force-logout over WebSocket and push notification.

Authentication:Bearer Token

Request Parameters

Parameter	Type	Required	Description
`device_id`	string	Required	The device_id of the session to revoke, as returned by GET /auth/devices. Maximum 255 characters.

Code Examples

curl -X POST https://api.orbai.world/api/v1/auth/logout-device \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "device_id": "9b2f7c10-44ad-4f0e-bb71-2c0f8e91d3aa" }'

Responses

200The device was signed out. The revoked device is notified in real time and on next app launch.

{
  "success": true,
  "data": {
    "success": true,
    "message": "Device logged out successfully",
    "device_id": "9b2f7c10-44ad-4f0e-bb71-2c0f8e91d3aa",
    "device_name": "Pixel 8 Pro"
  }
}

404The specified device was not found or is already logged out.

{
  "success": false,
  "error": {
    "code": "DEVICE_NOT_FOUND",
    "message": "The specified device was not found or is already logged out."
  }
}

When a user tries to sign in but has already reached their plan's device limit, the login response returns DEVICE_LIMIT_EXCEEDED along with the list of active devices and a short-lived device_logout_token. The user can then free a slot by signing out one of their existing devices without being authenticated — the device_logout_token authorizes the action.

POST/api/v1/auth/device-limit/logout

Sign out a device using a short-lived device_logout_token issued by a DEVICE_LIMIT_EXCEEDED login response. No bearer token required.

Authentication:No Auth Required

Request Parameters

Parameter	Type	Required	Description
`device_logout_token`	string	Required	The short-lived token returned in the device_logout_token field of a DEVICE_LIMIT_EXCEEDED login response. Expires after a few minutes.
`device_id`	string	Required	The device_id to sign out, chosen from the active_devices array of the login response. Maximum 255 characters.

Code Examples

curl -X POST https://api.orbai.world/api/v1/auth/device-limit/logout \
  -H "Content-Type: application/json" \
  -d '{
        "device_logout_token": "dlt_3f9a...",
        "device_id": "9b2f7c10-44ad-4f0e-bb71-2c0f8e91d3aa"
    }'

Responses

200The chosen device was signed out. The user can now retry login on the new device.

{
  "success": true,
  "data": {
    "success": true,
    "message": "Device logged out successfully",
    "device_id": "9b2f7c10-44ad-4f0e-bb71-2c0f8e91d3aa",
    "device_name": "Pixel 8 Pro"
  }
}

401The device_logout_token is invalid or has expired.

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The device logout token is invalid or expired."
  }
}

Typical Flow

User submits credentials to POST /auth/login. 2. Login returns DEVICE_LIMIT_EXCEEDED with active_devices and a device_logout_token. 3. Your UI lists the devices and lets the user pick one to remove. 4. Call this endpoint with the token and chosen device_id. 5. Retry the original login — a slot is now free.

Refresh Subscription Claims

After a user upgrades, renews, or changes their subscription, their existing access token still carries the old plan claims until it expires. Rather than forcing a full re-login, call refresh-claims to mint a fresh access token that reflects the latest subscription state.

POST/api/v1/auth/refresh-claims

Issue a new access token with up-to-date subscription claims for the authenticated user, without requiring a re-login.

Authentication:Bearer Token

Code Examples

curl -X POST https://api.orbai.world/api/v1/auth/refresh-claims \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response

200A new token pair carrying refreshed subscription claims.

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "bmV3IHJlZnJlc2ggdG9rZW4...",
    "access_token_expires_at": "2026-06-26T12:00:00Z",
    "refresh_token_expires_at": "2026-07-26T12:00:00Z",
    "token_type": "Bearer"
  }
}

When to Use refresh-claims vs. refresh

Use /auth/refresh to rotate an expiring token pair with the same claims. Use /auth/refresh-claims specifically after a subscription change so the new token reflects the upgraded plan, device limit, or feature entitlements immediately.

Verify Email

POST/api/v1/auth/verify-email

Confirm a user's email address using the verification token delivered in the verification email.

Authentication:No Auth Required

Request Parameters

Parameter	Type	Required	Description
`token`	string	Required	The email verification token from the link in the verification email. Single-use and time-limited.

Code Examples

curl -X POST https://api.orbai.world/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{ "token": "evt_a1b2c3d4..." }'

Responses

200Email verified successfully.

{
  "success": true,
  "data": {
    "success": true,
    "message": "Email verified successfully"
  }
}

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

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "This verification token is invalid, has expired, or has already been used."
  }
}

409The email address has already been verified.

{
  "success": false,
  "error": {
    "code": "EMAIL_ALREADY_VERIFIED",
    "message": "This email address is already verified."
  }
}

Login -- Email/password authentication (returns DEVICE_LIMIT_EXCEEDED when full)
Logout -- End the current session or all sessions
Refresh Token -- Rotate an expiring token pair
Password Reset & Change -- Recover or change credentials

Device Management & Sessions