Authentication Overview

Learn how Budget Bee handles authentication, session management, and JWT tokens

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": "[e-mail]",
  "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