Skip to main content

​
Authentication System

Budget Bee uses Better Auth with JWT (JSON Web Token) based authentication. The system supports multiple authentication methods including email/password and OAuth providers.

​
Base URL

All authentication endpoints are available at: 
{NEXT_PUBLIC_APP_URL}/api/auth

​
Authentication Methods

Budget Bee supports the following authentication methods:
  • Email/Password - Traditional email and password authentication
  • Google OAuth - Sign in with Google
  • Bearer Tokens - API access using JWT tokens

​
Session Management

​
Session Configuration

Sessions are stored in the database with the following fields:
​
id
string
required
Unique session identifier
​
user_id
string
required
Reference to the authenticated user
​
active_organization_id
string
Currently active organization for this session
​
expires_at
timestamp
required
When the session expires
​
ip_address
string
IP address of the client
​
user_agent
string
Browser/client user agent string
​
created_at
timestamp
Session creation timestamp
​
updated_at
timestamp
Last session update timestamp

​
JWT Token Structure

​
Token Payload

JWT tokens issued by Budget Bee contain the following claims: 
{
  "sub": "user_id",
  "user_id": "user_id",
  "role": "authenticated",
  "email": "[email protected]",
  "claims": {
    "organization_id": "org_id",
    "organization_role": "owner",
    "subscription": {
      "isSubscribed": true,
      "productId": "prod_123"
    }
  },
  "iss": "{NEXT_PUBLIC_APP_URL}",
  "aud": "{NEXT_PUBLIC_APP_URL}",
  "exp": 1234567890
}
​
sub
string
Subject - the user ID
​
user_id
string
User identifier (same as sub)
​
role
string
Always “authenticated” for logged-in users
​
email
string
User’s email address
​
claims.organization_id
string
Active organization ID (if any)
​
claims.organization_role
string
User’s role in the organization: owner, admin, editor, or viewer
​
claims.subscription
object
Current subscription information
​
iss
string
Token issuer
​
aud
string
Token audience
​
exp
number
Expiration timestamp (1 hour from issue)

​
Making Authenticated Requests

​
Using Bearer Token

Include the JWT token in the Authorization header: 
curl -X GET "{NEXT_PUBLIC_PG_REST_URL}/transactions" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json"

​
Using Cookies

For browser-based requests, sessions are automatically managed via secure HTTP-only cookies.

​
Email Verification

​
Requirements

  • Email verification is required for all new accounts
  • Verification emails are sent on sign-up and sign-in (if not verified)
  • Unverified users cannot create organizations

​
Verification Flow

  1. User signs up with email/password
  2. Verification email sent with unique link
  3. User clicks link to verify email
  4. Account becomes fully active

​
Security Features

​
Password Reset

Secure password reset flow with email verification:
  • Reset link expires after configured time
  • One-time use tokens
  • Email notification on password change

​
Account Linking

Trusted providers (Google) can be linked to existing accounts:
  • Prevents duplicate accounts
  • Seamless provider switching
  • Maintains single user identity

​
Database Roles

Budget Bee uses PostgreSQL row-level security (RLS) with specific roles:
  • anon - Anonymous/unauthenticated access
  • authenticated - Logged-in users
  • auth_admin - Special role for auth operations
  • subscription_admin - Subscription management operations

​
Next Steps

Email/Password Auth

Learn about email/password authentication endpoints

OAuth Setup

Configure Google OAuth authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us