Authentication API Reference

Request a password reset link

Always returns 200 regardless of whether the email exists, to prevent enumeration. Rate limited to 5 requests per hour per IP.

Authentication

None

Request Body

Response (Success)

Example Request

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

Example Response

{
  "message": "string"
}

Authenticate and receive a JWT token

Returns a JWT token on success. If the account has TOTP enabled and no totp_code is provided, returns 401 with totp_required: true. Rate limited to 10 requests per minute per IP.

Authentication

None

Request Body

Response (Success)

Example Request

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

Example Response

{
  "token": "string",
  "user": {
    "email": "user@example.com",
    "email_verified": false,
    "id": "00000000-0000-0000-0000-000000000000",
    "is_admin": false,
    "tier": "string",
    "totp_enabled": false,
    "username": "string"
  }
}

Get the authenticated user's full profile

Authentication

JWT Bearer Token

Response (Success)

Example Request

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

Example Response

{
  "user": {
    "email": "user@example.com",
    "email_verified": false,
    "id": "00000000-0000-0000-0000-000000000000",
    "points": 0,
    "referral_code": "string",
    "signup_multiplier": 0,
    "stats": {
      "connected_apps": 0,
      "direct_referrals": 0,
      "total_earned": 0,
      "total_spent": 0
    },
    "tier": "string",
    "tier_emoji": "string",
    "totp_enabled": false,
    "username": "string"
  }
}

Register a new user account

Creates a new user. Rate limited to 5 requests per hour per IP.

Authentication

None

Request Body

Response (Success)

Example Request

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

Example Response

{
  "user": {
    "email": "user@example.com",
    "email_verified": false,
    "id": "00000000-0000-0000-0000-000000000000",
    "points": 0,
    "referral_code": "string",
    "registration_number": 0,
    "tier": "string",
    "username": "string"
  }
}

Reset password using a reset token

Authentication

None

Request Body

Response (Success)

Example Request

curl -X POST "https://api.buddo.xyz/api/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "string",
  "token": "string"
}'

Example Response

{
  "message": "string"
}

Resend the email verification link

Authentication

JWT Bearer Token

Response (Success)

Example Request

curl -X POST "https://api.buddo.xyz/api/auth/send-verification" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "message": "string"
}

Enable TOTP by confirming a valid code

Requires a valid TOTP code from the authenticator app. Returns recovery codes on success — these should be stored securely by the user.

Authentication

JWT Bearer Token

Request Body

Response (Success)

Example Request

curl -X POST "https://api.buddo.xyz/api/auth/totp/enable" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string"
}'

Example Response

{
  "message": "string",
  "recovery_codes": [
    "string"
  ]
}

Generate a TOTP secret and provisioning URI

Authentication

JWT Bearer Token

Response (Success)

Example Request

curl -X POST "https://api.buddo.xyz/api/auth/totp/setup" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "secret": "string",
  "uri": "string"
}

Verify a TOTP or recovery code

Authentication

JWT Bearer Token

Request Body

Response (Success)

Example Request

curl -X POST "https://api.buddo.xyz/api/auth/totp/verify" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string"
}'

Example Response

{
  "message": "string"
}

Verify a user's email address with a token

Authentication

None

Request Body

Response (Success)

Example Request

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

Example Response

{
  "message": "string"
}

Register a new OAuth app

Creates a new OAuth app. Returns the client_secret — this is the only time it is shown. Rate limited to 3 requests per hour. **Requires email verification.** This endpoint is behind the `email_verified` pipeline. Your account email must be verified before you can register OAuth apps. If your email is not verified, this endpoint returns 403. To verify your email: call POST /api/auth/send-verification (requires JWT) to receive a verification code, then call POST /api/auth/verify-email with the code. After verification, retry this request with your JWT bearer token.

Authentication

JWT Bearer Token

Request Body

Response (Success)

Example Request

curl -X POST "https://api.buddo.xyz/api/oauth/apps" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "allowed_scopes": [
    "string"
  ],
  "app_description": "string",
  "app_name": "string",
  "logo_url": "string",
  "redirect_uris": [
    "string"
  ],
  "website_url": "string"
}'

Example Response

{
  "app": {
    "allowed_scopes": [
      "string"
    ],
    "app_description": "string",
    "app_name": "string",
    "client_id": "string",
    "id": "00000000-0000-0000-0000-000000000000",
    "inserted_at": "2026-01-01T00:00:00Z",
    "is_approved": false,
    "logo_url": {},
    "redirect_uris": [
      "string"
    ],
    "website_url": {},
    "client_secret": "string"
  }
}

Get public app metadata by client_id

Returns public app information. No authentication required.

Authentication

None

Path Parameters

Response (Success)

Example Request

curl -X GET "https://api.buddo.xyz/api/oauth/apps/:client_id"

Example Response

{
  "client_id": "string",
  "description": "string",
  "name": "string"
}

Request an authorization code

Issues an authorization code for the given client_id. Requires PKCE with S256 method. The code is valid for 600 seconds.

Authentication

JWT Bearer Token

Query Parameters

Response (Success)

Example Request

curl -X GET "https://api.buddo.xyz/api/oauth/authorize?client_id=VALUE&response_type=VALUE&code_challenge=VALUE&code_challenge_method=VALUE" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "code": "string",
  "expires_in": 0,
  "redirect_uri": "string"
}

List OAuth apps owned by the authenticated user

Authentication

JWT Bearer Token

Example Request

curl -X GET "https://api.buddo.xyz/api/oauth/my-apps" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

[
  {
    "allowed_scopes": [
      "string"
    ],
    "app_description": "string",
    "app_name": "string",
    "client_id": "string",
    "id": "00000000-0000-0000-0000-000000000000",
    "inserted_at": "2026-01-01T00:00:00Z",
    "is_approved": false,
    "logo_url": {},
    "redirect_uris": [
      "string"
    ],
    "website_url": {}
  }
]

Update an OAuth app owned by the authenticated user

Authentication

JWT Bearer Token

Path Parameters

Request Body

Response (Success)

Example Request

curl -X PUT "https://api.buddo.xyz/api/oauth/my-apps/:id" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "allowed_scopes": [
    "string"
  ],
  "app_description": "string",
  "app_name": "string",
  "logo_url": "string",
  "redirect_uris": [
    "string"
  ],
  "website_url": "string"
}'

Example Response

{
  "allowed_scopes": [
    "string"
  ],
  "app_description": "string",
  "app_name": "string",
  "client_id": "string",
  "id": "00000000-0000-0000-0000-000000000000",
  "inserted_at": "2026-01-01T00:00:00Z",
  "is_approved": false,
  "logo_url": {},
  "redirect_uris": [
    "string"
  ],
  "website_url": {}
}

Request additional scopes for an owned app

Submits a request to expand the app's allowed scopes. Requires admin approval. **Manual approval process:** Scope requests are reviewed manually by a Buddo admin — there is no automated approval. Approval times vary and there is no webhook or callback; poll GET /api/oauth/my-apps/{id}/scope-requests to check status. A `pending` status means the request is awaiting review. **deploy:manage is not auto-approved.** This scope grants full deployment management and requires explicit admin sign-off. Submit the request, then contact Buddo support to expedite review.

Authentication

JWT Bearer Token

Path Parameters

Request Body

Response (Success)

Example Request

curl -X POST "https://api.buddo.xyz/api/oauth/my-apps/:id/scope-request" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "requested_scopes": [
    "string"
  ]
}'

Example Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "inserted_at": "2026-01-01T00:00:00Z",
  "requested_scopes": [
    "string"
  ],
  "status": "string"
}

Exchange an authorization code or refresh token for access tokens

Supports two grant types: 'authorization_code' (with PKCE code_verifier for public clients or client_secret for confidential clients) and 'refresh_token'. Authorization code grants also return a session_token for lightweight session maintenance.

Authentication

None

Request Body

One of the following:

Authorization Code Grant

Refresh Token Grant

Response (Success)

Example Request

curl -X POST "https://api.buddo.xyz/api/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "string",
  "client_secret": "string",
  "code": "string",
  "code_verifier": "string",
  "grant_type": "authorization_code",
  "redirect_uri": "string"
}'

Example Response

{
  "access_token": "string",
  "expires_in": 0,
  "refresh_token": "string",
  "session_token": "string",
  "session_token_expires_at": "2026-01-01T00:00:00Z",
  "token_type": "Bearer"
}

Introspect an access token

Returns token validity and metadata. Always returns 200 — check the 'active' field. No authentication required.

Authentication

None

Request Body

Response (Success)

Example Request

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

Example Response

{
  "active": false,
  "app_id": "00000000-0000-0000-0000-000000000000",
  "expires_at": "2026-01-01T00:00:00Z",
  "reason": "string",
  "scopes": [
    "string"
  ],
  "user_id": "00000000-0000-0000-0000-000000000000"
}

Refresh a session token

Validates the current session token, sends a heartbeat, and returns a rotated token. The old token is invalidated atomically. Rate limited to 20 requests per minute per IP. Does not use JWT — authenticates via the session_token in the request body.

Authentication

None

Request Body

Response (Success)

Example Request

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

Example Response

{
  "expires_at": "2026-01-01T00:00:00Z",
  "session_token": "string"
}