Quickstart

Register an account, authenticate, and make your first authenticated API call. This guide takes about 10 minutes.

Prerequisites

You need curl or any HTTP client. That's it. All examples below use curl, but the same requests work from any language or tool that can send HTTP requests.

Step 1: Register an account

Create a new user account by sending a POST request to /api/auth/register with your email, a username, and a password (minimum 8 characters). You can optionally include a referral_code.

Request

curl -X POST https://api.buddo.xyz/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "username": "myapp",
    "password": "a-strong-password"
  }'

Response 201

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "test@example.com",
    "username": "myapp",
    "tier": "free",
    "points": 0,
    "referral_code": "ABC123",
    "email_verified": false,
    "registration_number": 42
  }
}

Your account is created but email is not yet verified. Check your inbox for a verification email.

Step 2: Verify your email

You'll receive an email with a verification token. Send it to /api/auth/verify-email to confirm your address.

Request

curl -X POST https://api.buddo.xyz/api/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your-verification-token"
  }'

Response 200

{
  "message": "Email verified"
}

If the token is invalid or expired, you'll receive a 400 error. You can request a new verification email by calling POST /api/auth/send-verification with a valid JWT (see Step 3).

Step 3: Log in and get a JWT

Authenticate with your email and password to receive a JWT token. This token is used to authorize all subsequent API requests.

Request

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

Response 200

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

Save the token value. You'll pass it as a Bearer token in the Authorization header for authenticated requests.

Step 4: Make an authenticated request

Use your JWT to fetch your full profile from GET /api/auth/me. Pass the token in the Authorization header.

Request

curl https://api.buddo.xyz/api/auth/me \
  -H "Authorization: Bearer your-jwt-token-here"

Response 200

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "test@example.com",
    "username": "myapp",
    "tier": "free",
    "tier_emoji": "",
    "points": 0,
    "referral_code": "ABC123",
    "signup_multiplier": 1,
    "email_verified": true,
    "totp_enabled": false,
    "stats": {
      "direct_referrals": 0,
      "connected_apps": 0,
      "total_earned": 0,
      "total_spent": 0
    }
  }
}

If you see your profile, your authentication is working. Any request without a valid JWT will return 401 Unauthorized.

Step 5: Explore the API

Now that you can authenticate, you have access to the full platform. The API has 57 endpoints across nine domains:

• Auth — Registration, login, TOTP, password reset
• OAuth — App registration, authorization codes, token exchange
• Deploy — Container deployments on buddocloud
• Social — Friends, presence, chat, user search
• Operator — App management and analytics
• User — Connected apps and profile management
• Points — Balance, spend, transfer
• Ads — Serve campaigns and record events
• Education — Learning paths and modules

The full OpenAPI 3.1 specification is available at:
https://api.buddo.xyz/.well-known/openapi.json

Or browse the generated API Reference for every endpoint with request/response schemas.

What's next

You're authenticated and ready to build. Here are the most common next steps: