Request Parameters

Parameter	Type	Required	Description
`email`	string	Required	The email address associated with the user account.
`password`	string	Required	The user's password.
`totp_code`	string	Optional	6-digit TOTP code from an authenticator app. Required only when the account has two-factor authentication enabled.
`device_id`	string	Optional	Unique device identifier (UUID recommended). Used for device tracking and session management.
`platform`	string	Optional	Client platform. One of: ios, android, windows, macos, linux, web.
`device_name`	string	Optional	Human-readable device name, e.g. "iPhone 15 Pro" or "Chrome on MacBook".
`fcm_token`	string	Optional	Firebase Cloud Messaging token for push notifications.

Code Examples

curl -X POST https://api.orbai.world/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
        "email": "user@example.com",
        "password": "your_password",
        "totp_code": "482910",
        "device_id": "550e8400-e29b-41d4-a716-446655440000",
        "platform": "ios",
        "device_name": "iPhone 15 Pro",
        "fcm_token": "eyJhbGciOiJIUzI1NiIs..."
    }'

Responses

200Authentication successful. Returns user profile, JWT tokens, and subscription information.

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "uuid": "usr_abc123",
      "username": "john_doe",
      "email": "user@example.com",
      "role": "USER",
      "active": true
    },
    "tokens": {
      "access_token": "eyJhbGciOiJIUzI1NiIs...",
      "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2...",
      "access_token_expires_at": "2026-02-09T12:00:00Z",
      "refresh_token_expires_at": "2026-03-08T12:00:00Z",
      "token_type": "Bearer"
    },
    "subscription": {
      "plan_name": "Premium",
      "status": "active",
      "expires_at": "2026-12-31T23:59:59Z"
    },
    "requires_2fa": false
  }
}

401Invalid email or password.

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

422Validation error. One or more fields failed validation.

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

429Too many login attempts. Rate limited.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many login attempts. Please try again later."
  }
}

Register -- Register
Refresh Token -- Refresh Token
OAuth Login -- OAuth Login
Magic Link -- Magic Link
Passkeys -- Passkeys

Login

Login

Request Parameters

Code Examples

Responses

Related Endpoints

On this page