Authenticate users via third-party OAuth providers. If the user does not already have an account, one is created automatically on first login.

POST/api/v1/auth/oauth/login

Authenticate or register a user using an OAuth access token from a supported provider. New accounts are created automatically for first-time users.

Authentication:No Auth Required

Request Parameters

Parameter	Type	Required	Description
`provider`	string	Required	OAuth provider name. One of: google, apple, facebook, github.
`token`	string	Required	OAuth access token (or ID token for Apple) obtained from the provider's authentication flow.
`device_id`	string	Optional	Unique device identifier (UUID recommended).
`platform`	string	Optional	Client platform. One of: ios, android, windows, macos, linux, web.
`device_name`	string	Optional	Human-readable device name.
`fcm_token`	string	Optional	Firebase Cloud Messaging token for push notifications.

Code Examples

curl -X POST https://api.orbai.world/api/v1/auth/oauth/login \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "token": "ya29.a0AfH6SMB...",
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "platform": "android",
    "device_name": "Pixel 8 Pro"
  }'

Responses

200Authentication successful. Returns the standard AuthResponse with user profile, JWT tokens, and subscription. For new users, an account is created automatically using profile data from the OAuth provider.

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "uuid": "usr_abc123",
      "username": "john_doe",
      "email": "user@gmail.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": "Free",
      "status": "active",
      "expires_at": null
    },
    "requires_2fa": false,
    "is_new_user": true
  }
}

401The OAuth token is invalid or has expired.

{
  "success": false,
  "error": {
    "code": "INVALID_OAUTH_TOKEN",
    "message": "The provided OAuth token is invalid or has expired. Please re-authenticate with the provider."
  }
}

422Validation error. Invalid provider or missing required fields.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "details": {
      "provider": "Must be one of: google, apple, facebook, github."
    }
  }
}

Auto-Registration

When a user authenticates via OAuth for the first time and no matching account exists, a new account is created automatically using the name and email from the provider. The response includes is_new_user: true so your client can show a welcome screen or onboarding flow.

Apple Sign In

For Apple Sign In, use the ID token (not the access token) as the token parameter. Apple only provides the user's name on the first authentication, so it cannot be retrieved on subsequent logins.

List Linked OAuth Accounts

GET/api/v1/auth/oauth/accounts

Retrieve a list of all OAuth providers linked to the authenticated user's account.

Authentication:Bearer Token

Code Examples

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

Response

200List of linked OAuth providers.

{
  "success": true,
  "data": {
    "accounts": [
      {
        "provider": "google",
        "provider_email": "user@gmail.com",
        "linked_at": "2026-01-15T10:30:00Z"
      },
      {
        "provider": "github",
        "provider_email": "user@github.com",
        "linked_at": "2026-02-01T14:20:00Z"
      }
    ]
  }
}

Link OAuth Provider

POST/api/v1/auth/oauth/link

Link a new OAuth provider to the authenticated user's account. This allows the user to log in with multiple social providers.

Authentication:Bearer Token

Request Parameters

Parameter	Type	Required	Description
`provider`	string	Required	OAuth provider to link. One of: google, apple, facebook, github.
`token`	string	Required	OAuth access token from the provider's authentication flow.

Code Examples

curl -X POST https://api.orbai.world/api/v1/auth/oauth/link \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "token": "gho_xxxxxxxxxxxx"
  }'

Responses

200OAuth provider linked successfully.

{
  "success": true,
  "data": {
    "provider": "github",
    "provider_email": "user@github.com",
    "linked_at": "2026-02-08T16:45:00Z"
  }
}

409This provider is already linked to this account or to another account.

{
  "success": false,
  "error": {
    "code": "PROVIDER_ALREADY_LINKED",
    "message": "This provider is already linked to your account or to another account."
  }
}

Unlink OAuth Provider

DELETE/api/v1/auth/oauth/unlink

Remove an OAuth provider from the authenticated user's account. The user must have at least one remaining authentication method (password or another linked provider).

Authentication:Bearer Token

Request Parameters

Parameter	Type	Required	Description
`provider`	string	Required	The OAuth provider to unlink. One of: google, apple, facebook, github.

Code Examples

curl -X DELETE https://api.orbai.world/api/v1/auth/oauth/unlink \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google"
  }'

Responses

200OAuth provider unlinked successfully.

{
  "success": true,
  "data": {
    "message": "Successfully unlinked google from your account."
  }
}

400Cannot unlink the only remaining authentication method.

{
  "success": false,
  "error": {
    "code": "LAST_AUTH_METHOD",
    "message": "Cannot unlink your only authentication method. Please set a password or link another provider first."
  }
}

Supported Providers

Provider	Token Type	Notes
google	OAuth access token	Standard Google OAuth 2.0 flow
apple	ID token (JWT)	Use the ID token, not the authorization code. Name is only available on first sign-in.
facebook	OAuth access token	Requires `email` permission scope
github	OAuth access token	Requires `user:email` scope

Login -- Email/password authentication
Register -- Create account with email
Passkeys -- WebAuthn/FIDO2 authentication

OAuth Social Login

Request Parameters

Code Examples

Responses

Auto-Registration

Apple Sign In

List Linked OAuth Accounts

Code Examples

Response

Link OAuth Provider

Request Parameters

Code Examples

Responses

Unlink OAuth Provider

Request Parameters

Code Examples

Responses

Supported Providers

On this page

OAuth Social Login