JWT vs OAuth Tokens

Buddo supports two authentication methods: JWT (direct operator authentication) and OAuth (delegated user authentication). This guide explains what each does, when to use it, and how they work together.

Quick Comparison

JWT Authentication

JWT auth is the simplest way to interact with the Buddo API. You log in with an email and password, receive a token, and pass it as a Bearer token on every request. This is operator-level access — the token represents your account directly.

Getting a JWT

Send a POST request to /api/auth/login with your credentials.

Request

curl -X POST https://api.buddo.xyz/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "operator@example.com",
    "password": "your-password"
  }'

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "operator@example.com",
    "username": "myoperator",
    "tier": "free",
    "is_admin": false,
    "email_verified": true,
    "totp_enabled": false
  }
}

Using the JWT

Pass the token in the Authorization header on every request.

curl https://api.buddo.xyz/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

What It Grants

A JWT gives direct access to all bearerAuth-protected endpoints. These span several API domains:

• Auth — /api/auth/me, TOTP setup/verify, email verification, password reset
• OAuth management — /api/oauth/my-apps, create/update apps, request scopes
• Social — friends, presence, chat, user search, blocking
• Education — learning paths, modules, step completion
• User — connected apps, app revocation
• Sessions — /api/session/refresh

Token Structure and Lifetime

The JWT is a standard signed JSON Web Token containing the user ID and account metadata. The AuthResponse schema returns:

Refreshing Sessions

For long-running connections, Buddo provides a session token that can be rotated via POST /api/session/refresh. This endpoint validates the current session token, sends a heartbeat, and returns a new rotated token. The old token is invalidated atomically.

curl -X POST https://api.buddo.xyz/api/session/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "current-session-token"
  }'

Response 200

{
  "session_token": "new-rotated-token",
  "expires_at": "2026-05-22T12:00:00Z"
}

Best For

• Admin dashboards and internal tools
• Backend services that manage your OAuth apps
• Operator-level account management (TOTP, email, password)
• Social features used by the account owner directly
• Quick prototyping before implementing full OAuth

OAuth Authentication

OAuth is how your application acts on behalf of a Buddo user. Instead of using your own credentials, the user authorizes your app to access specific data and actions through scope-based permissions.

How It Works

Buddo implements OAuth 2.0 Authorization Code with PKCE (S256). Plain code challenges are not supported. The full flow is covered in the OAuth PKCE Flow guide. Here is the summary:

1. Register an app — POST /api/oauth/apps (requires JWT)
2. Redirect user — GET /api/oauth/authorize with code_challenge
3. Exchange code — POST /api/oauth/token with code_verifier
4. Use access token — pass as Bearer token on /api/external/* endpoints
5. Refresh — POST /api/oauth/token with grant_type: refresh_token

What It Grants

OAuth tokens provide access to the external API surface — endpoints designed for apps acting on behalf of users:

• User — GET /api/external/user (profile)
• Points — balance, spend, transfer via /api/external/points/*
• Sessions — status, end via /api/external/session/*
• Ads — serve campaigns, record events via /api/external/ads/*
• App balance — GET /api/external/app/balance
• Operator — app details, analytics, updates via /api/operator/*
• Deploy — full deployment lifecycle via /api/deploy/*

Scope-Based Permissions

OAuth tokens are scoped — your app only gets access to what it asks for and what the user approves. Available scopes:

Access + Refresh Token Model

The OAuthTokenResponse from POST /api/oauth/token includes:

When the access token expires, exchange the refresh token for a new pair:

curl -X POST https://api.buddo.xyz/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "your-refresh-token",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

Token Introspection

Verify any access token's validity and metadata with POST /api/oauth/token/verify. No authentication required. Check the active field.

curl -X POST https://api.buddo.xyz/api/oauth/token/verify \
  -H "Content-Type: application/json" \
  -d '{ "token": "access-token-to-check" }'

Response 200

{
  "active": true,
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "app_id": "660e8400-e29b-41d4-a716-446655440000",
  "scopes": ["profile:read", "points:read"],
  "expires_at": "2026-05-22T12:00:00Z"
}

Best For

• User-facing apps (games, loyalty programs, storefronts)
• Third-party integrations that need user consent
• Apps that spend or transfer user points
• Serving ads and tracking events
• Container deployments on buddocloud

Decision Flowchart

Walk through these questions to pick the right auth method:

Are you building a user-facing app?
  +-- YES --> Does it need to act on behalf of individual users?
  |             +-- YES --> OAuth (PKCE flow)
  |             +-- NO  --> JWT may suffice for read-only public data
  +-- NO  --> Are you building an admin tool or backend service?
                +-- YES --> JWT
                +-- NO  --> Do you need user-specific data (points, profile, sessions)?
                              +-- YES --> OAuth
                              +-- NO  --> Do you need operator-level access (app management, analytics)?
                                            +-- YES --> Could be either:
                                            |            - JWT for /api/oauth/my-apps/*
                                            |            - OAuth for /api/operator/*
                                            +-- NO  --> Public endpoints need no auth at all

Migration Path: JWT to OAuth

Many operators start with JWT for speed and migrate to OAuth when they need user-level auth. Here is the typical progression:

Phase 1: JWT Only

1. Register an account and log in to get a JWT
2. Build your admin tools and backend services against /api/auth/* endpoints
3. Manage your operator settings, TOTP, and social features

Phase 2: Add OAuth

1. Register an OAuth app via POST /api/oauth/apps (this requires your JWT)
2. Store the client_id and client_secret securely — the secret is shown only once
3. Implement the PKCE authorization flow in your user-facing app
4. Request the scopes your app needs (e.g. profile:read, points:spend)

Phase 3: Full Production

1. Your backend uses JWT for operator-level tasks (managing the app, checking analytics)
2. Your frontend uses OAuth tokens for user-facing operations (reading profiles, spending points, serving ads)
3. Both auth methods coexist — they serve different purposes and access different endpoint groups

Common Patterns

Pattern 1: Operator Dashboard (JWT)

An internal dashboard where you manage your Buddo account, view analytics, and configure your OAuth apps.

Pattern 2: Loyalty Rewards Game (OAuth)

A user-facing game where players earn and spend Buddo points. The app acts on behalf of each player.

Pattern 3: Analytics Backend (JWT)

A server-side service that monitors your operator app's performance. No user interaction required.

Endpoint-to-Auth Quick Reference

A fast lookup of which authentication method each endpoint group requires.

Related Guides