Authentication Flow with Better Auth Plugins

This document describes the complete authentication and authorization flow across the Gremlin system with the Better Auth plugin architecture.

This document covers how you sign in and how tokens are minted and verified. For which module a signed-in user can reach, see Module Access Control.

System Architecture Overview

An interactive, zoomable version of this diagram is available at authentication-flow.html.

Key boundaries

Bun owns every auth write. Go reads the auth tables directly but never writes them (ADR-0006). All role mutations go through the Better Auth API on Bun.
Two secrets, two token types. The app-JWT is HS256 signed with BETTER_AUTH_SECRET, shared by Bun and Go. The PowerSync sync token is asymmetric, signed with a private key from the jwks table, so PowerSync only ever receives public keys.
Redis is the revocation channel, not a permission cache. Both backends read the same authInvalidBefore:<userId> marker.
Rental bypasses Bun. /api/rental/* is proxied by the SolidStart server straight to Go, forwarding the session cookie with Better Auth’s HMAC suffix stripped.
Mobile never calls Go directly. The app has a single API_BASE_URL pointing at Bun; every Go-owned mobile path (/api/mobile/sync/*, the fieldforce routes) needs an explicit proxy route in api-gateway/routes/index.ts or the app gets a misleading 404. Go re-validates the JWT behind that proxy.

1. User Registration Flow

Step-by-Step Process

Frontend (Astro / SolidStart)
  │
  ├─ User enters: email, password, name
  │
  ▼
POST /api/auth/sign-up
{
  "email": "user@example.com",
  "password": "secure_password_123",
  "name": "John Doe"
}

1.2 Bun Backend Processes Registration

Bun Backend (Better Auth)
  │
  ├─ Validate email format
  ├─ Check for duplicate email
  ├─ Hash password using scrypt
  │
  ├─ Create "users" table entry
  │  └─ id: nanoid (26 chars)
  │  └─ email: user@example.com
  │  └─ name: John Doe
  │  └─ emailVerified: false
  │  └─ isAnonymous: false
  │  └─ role: "user" (default)
  │
  ├─ Create "accounts" table entry (password hash)
  │  └─ userId: nanoid_26
  │  └─ password: scrypt hash (Better Auth default)
  │  └─ providerId: "credential"
  │
  ├─ Create "sessions" table entry
  │  └─ userId: nanoid_26
  │  └─ token: random session token
  │  └─ expiresAt: Better Auth default (no override in di-container.ts)
  │  └─ activeOrganizationId: null (set by the organization plugin)
  │
  ▼
Return SESSION (Set-Cookie) to Frontend

Sign-up and sign-in return a session, not a JWT. Better Auth issues a session cookie (or a bearer session token). The app-JWT that the Go backend verifies is minted by a separate exchange — see Section 3.

1.3 Frontend Receives the Session

Frontend
  │
  ├─ Session cookie is set by the server (HttpOnly)
  │
  ├─ Redirect to landing path for the user's role
  │  └─ 'landlord' → /owner, everyone else → /
  │     (apps/panel/src/lib/platform-role.ts)
  │
  ▼
User authenticated

Step-by-Step Process

Frontend (Astro / SolidStart)
  │
  ├─ User enters: email, password
  │
  ▼
POST /api/auth/sign-in
{
  "email": "user@example.com",
  "password": "secure_password_123"
}

2.2 Bun Backend Verifies Credentials

Bun Backend (Better Auth)
  │
  ├─ Lookup user by email in "users" table
  │
  ├─ Fetch password hash from "accounts" table
  │
  ├─ Compare provided password with stored hash
  │  ├─ If match: proceed
  │  ├─ If no match: return 401 Unauthorized
  │
  ├─ Create/Update "sessions" table entry
  │  └─ token: new random session token
  │  └─ expiresAt: Better Auth default
  │
  ▼
Return SESSION (Set-Cookie) to Frontend

2.3 Frontend Receives the Session

Frontend
  │
  ├─ Session cookie is set (same as sign-up)
  ├─ Redirect to the role's landing path
  │
  ▼
User authenticated

3. App-Token Exchange (Session → JWT)

Clients that cannot rely on cookies — the mobile app, and any caller that needs a bearer token for the Go backend — exchange their live session for an HS256 app-JWT.

POST /api/v1/auth/app-token
Cookie: better-auth.session_token=...        (or bearer session token)
x-client-platform: ios | android | web

Bun Backend (services/auth/api.ts)
  │
  ├─ auth.api.getSession(headers)             ← live session ONLY
  │  └─ 401 if absent or revoked
  │
  ├─ Re-read authoritative state at mint time (never trust cached claims)
  │  ├─ users:   email, email_verified, role, banned
  │  └─ members: organization_id, role         (first membership row)
  │
  ├─ Refuse to mint for a banned account (403)
  │
  ├─ buildRoles(orgRole, platformRole)
  │  └─ org role FIRST, platform role second, de-duplicated
  │  └─ falls back to ['user'] so Go's ">= 1 role" rule always holds
  │
  ├─ Sign HS256 with BETTER_AUTH_SECRET, TTL = 7d (APP_TOKEN_TTL)
  │
  └─ Claims:
     {
       "sub":            "nanoid_26",
       "userId":         "nanoid_26",
       "email":          "user@example.com",
       "roles":          ["member", "admin"],
       "organizationId": "nanoid_26",
       "isActive":       true,
       "emailVerified":  false,
       "platform":       "ios",
       "iat": 1713265800,
       "exp": 1713870600
     }

This endpoint deliberately does not use the generic authMiddleware. That middleware also accepts an app-JWT, which would let a stolen or logged-out token refresh itself indefinitely. getSession honours only a live session, so revoking the session cuts off new mints.

Two different tokens exist. Do not confuse them.

Token	Algorithm	Signed with	Used by
App-JWT	HS256 (symmetric)	`BETTER_AUTH_SECRET`	Go backend, Bun middleware
PowerSync sync token	asymmetric (JWKS)	private key in the `jwks` table	PowerSync only

The sync token is short-lived and comes from Better Auth’s jwt plugin (/api/auth/token + /api/auth/jwks), so PowerSync receives verify-only public keys and never the shared secret.

buildRoles is re-implemented on both sides of the trust boundary — Bun (services/auth/api.ts) and Go (internal/api/http/middleware/better_auth_validator.go). The behaviour is pinned by contracts/auth/role-revocation-vectors.json; change one side without the other and TestAuthGoldenVectors (Go) or auth-golden.test.ts (Bun) fails.

4. Authenticated Request Flow (Go Backend)

Step-by-Step Process

4.1 Frontend Makes Authenticated Request

Frontend (Astro / SolidStart)
  │
  ├─ Include JWT in Authorization header
  │
  ▼
GET /api/v1/users/me
Authorization: Bearer eyJhbGc... (JWT)

4.2 Bun Backend Verifies JWT (if applicable)

Note: If API Gateway is Bun-based, verification happens here
Bun Backend API Gateway
  │
  ├─ Extract JWT from Authorization header
  ├─ Verify signature using BETTER_AUTH_SECRET
  ├─ Check token expiration
  ├─ Attach decoded payload to request context
  │
  ▼
Forward to appropriate backend service

4.3 Go Backend Processes Request

Go Backend (api/v1)
  │
  ├─ Extract JWT from Authorization header
  │
  ├─ Verify JWT signature using BETTER_AUTH_SECRET
  │  (Same secret as Bun, ensures trust)
  │
  ├─ Check the revocation marker (see Section 9)
  │  └─ reject if iat predates authInvalidBefore:<userId>
  │
  ├─ Populate the Echo context:
  │  user_id, session_id, organization_id,
  │  user_roles, is_active, email_verified, is_anonymous
  │
  ├─ Extract userId from JWT claims
  │
  ├─ Query user from PostgreSQL
  │  SELECT * FROM "users" WHERE id = ?
  │
  ├─ Return user data
  │  {
  │    "id": "nanoid_26",
  │    "email": "user@example.com",
  │    "name": "John Doe",
  │    "role": "user",
  │    "emailVerified": false,
  │    "isAnonymous": false,
  │    "image": null,
  │    "createdAt": "2024-04-16T10:30:00Z",
  │    "updatedAt": "2024-04-16T10:30:00Z"
  │  }
  │
  ▼
Frontend receives user data

5. Organization Management Flow

Organization writes are split across two surfaces. Do not assume everything lives under /api/auth/organization/*:

Better Auth plugin endpoints — mounted by the catch-all app.all('/api/auth/*') handler. Used for org creation and the plugin’s own member primitives.
Custom self-service API — a Hono router at /api/v1/organizations/* (services/organizations/api.ts), plus custom roles at the same mount and a platform-admin variant at /api/v1/admin/organizations/*.

The route list in Section 12 is authoritative.

5.1 Create Organization

Frontend
  │
  ├─ Authenticated user clicks "Create Organization"
  │
  ▼
POST /api/auth/organization/create
Authorization: Bearer <JWT>
{
  "name": "Acme Corp",
  "slug": "acme-corp"
}

Bun Backend (Organization Plugin)
  │
  ├─ Verify JWT and extract userId
  │
  ├─ Validate organization name/slug
  │
  ├─ Create "organizations" table entry
  │  └─ id: nanoid_26
  │  └─ name: Acme Corp
  │  └─ slug: acme-corp (unique)
  │  └─ creatorId: userId (from JWT)
  │  └─ createdAt: now
  │
  ├─ Create "members" table entry (creator as owner)
  │  └─ userId: nanoid_26
  │  └─ organizationId: nanoid_26
  │  └─ role: "owner"
  │  └─ joinedAt: now
  │
  ▼
Return organization data with member role

5.2 Invite Member to Organization

Frontend
  │
  ├─ Org admin clicks "Invite Member"
  │ ├─ Enters email: "member@example.com"
  │ ├─ Selects role: "staff"
  │
  ▼
POST /api/v1/organizations/:orgId/invitations
Authorization: Bearer <JWT>          (or session cookie)
{
  "email": "member@example.com",
  "role": "staff"
}

Bun Backend (services/organizations/api.ts)
  │
  ├─ Resolve caller and check org membership permission
  │
  ├─ Validate body against InviteMemberSchema (Zod)
  │
  ├─ Create "invitations" table entry
  │  └─ organizationId, inviterId, email, role
  │  └─ status: "pending"
  │  └─ expiresAt
  │
  ├─ Write an audit_logs entry
  │
  ▼
Return invitation data

A members row is created only when the invitation is accepted — an invitation and a membership are separate records. Related routes on the same mount:

GET    /api/v1/organizations/:orgId/invitations                 list
DELETE /api/v1/organizations/:orgId/invitations/:invitationId   revoke

5.3 Change a Member’s Role

PATCH /api/v1/organizations/:orgId/members/:memberId
{ "role": "admin" }
  │
  ├─ Update members.role
  ├─ Write audit_logs entry
  ├─ CacheInvalidator fires  → see Section 6.2
  ▼
Return updated member

6. Permission Query Flow (Go Backend)

6.1 Authorization for Protected Operations

Frontend wants to approve a leave request
  │
  ├─ User makes request to Go backend
  │
  ▼
POST /api/v1/leave/requests/:id/approve
Authorization: Bearer <JWT>
{
  "approverId": "user_id"
}

Go Backend
  │
  ├─ Extract userId from JWT
  ├─ Extract organizationId from request context
  │
  ├─ Call PermissionService.CanUserApproveLease(
  │    userId, organizationId
  │  )
  │
  ├─ PermissionService checks:
  │  ├─ Query members table:
  │  │  SELECT role FROM members
  │  │  WHERE user_id = ? AND organization_id = ?
  │  │
  │  ├─ Map role → permission set (defaultRolePermissions)
  │  │
  │  ├─ Cache result IN PROCESS for 5 minutes
  │  │  (sync.Map TTL cache, not Redis)
  │
  ├─ If authorized: proceed with approval
  ├─ If not authorized: return 403 Forbidden
  │
  ▼
Return result

The Go permission cache is a per-process in-memory sync.Map with a 5-minute TTL (permission_service.go), not Redis. Consequences:

Each replica caches independently. There is no shared invalidation across pods.
InvalidateOrgCache is brute force — it replaces the whole cache object rather than deleting selected keys.
Redis is used in this system, but for app-JWT revocation (Section 9), not for this cache.

6.2 Cache Invalidation Flow

Invalidation happens inside the Bun backend, at the point of the write:

Org admin changes a member's role

Bun Backend (services/cache/cache-invalidator.ts)
  │
  ├─ UPDATE members SET role = 'admin' WHERE id = ?
  │
  ├─ CacheInvalidator fires on:
  │  member role change, team change,
  │  custom-role permission change, team role assignment
  │
  ├─ 1. Clear the Bun permission cache
  │
  ├─ 2. Revoke the affected users' app-JWTs
  │     markUserTokensInvalid() → Redis key
  │     authInvalidBefore:<userId> = now  (TTL 8 days)
  │     The acting user is deliberately EXCLUDED,
  │     so admins do not log themselves out.
  │
  ▼
Affected users' next request is rejected → re-mints with fresh claims

Go Backend
  │
  ├─ better_auth_validator.go reads the same Redis marker
  │  └─ rejects any JWT whose iat predates it
  │
  ├─ The in-process permission cache is NOT signalled —
  │  it clears on its own 5-minute TTL
  │
  ▼
Permission checks use the updated role within 5 minutes

MemberRoleChangeConsumer is dead code. The file exists at internal/modules/organizations/adapter/inbound/messaging/member_role_change_consumer.go, but NewMemberRoleChangeConsumer has zero callers — no NATS member.role.changed subscription is wired. Earlier revisions of this document described that flow as live; it is not. Do not rely on it.

7. Role Hierarchy & Permissions

Platform Roles (Better Auth Admin Plugin)

Stored in: "users".role field — a SINGLE text value

Roles:
├─ superadmin  → System administrator
├─ admin       → Platform administrator
├─ landlord    → Rental platform property owner
└─ user        → Regular user (default)

users.role holds one value only. An account cannot be both landlord and admin — PromoteToLandlord explicitly refuses accounts holding a staff role, because writing landlord would destroy it.The rental role is named landlord, not owner, on purpose: owner already means organization owner, and buildRoles flattens org and platform roles into one array, so reusing owner would make the two meanings indistinguishable inside a token.

Organization Roles (Better Auth Organization Plugin)

Stored in the members.role field, per (userId, organizationId). The permission set is resolved from defaultRolePermissions in permission_service.go — permissions are not stored in a table.

Org role	Permissions
`owner`	`data:read`, `data:write`, `leave:approve`, `leave:request`, `member:invite`, `member:manage`, `member:remove`, `org:manage`
`admin`	identical to `owner`
`staff`	`data:read`, `data:write`, `leave:request`
`member`	`data:read`, `data:write`, `leave:request`
`viewer`	`data:read`

staff does NOT have leave:approve. Earlier revisions of this document said it did. Only owner and admin can approve leave. staff and member currently resolve to the same permission set.

field_team is a further org role used by the fieldforce module. It is not in defaultRolePermissions — it is checked inline in fieldforce handlers to restrict field workers from briefings and risk data. Organizations can also define custom roles (custom_roles table, referenced by members.custom_role_ids). For how these roles map to module access, see Module Access Control.

8. Error Handling

Common Error Scenarios

Scenario	Status Code	Response
Missing/Invalid JWT	401	`{ "error": "Unauthorized", "message": "Invalid token" }`
Expired JWT	401	`{ "error": "Unauthorized", "message": "Token expired" }`
Insufficient permissions	403	`{ "error": "Forbidden", "message": "Insufficient permissions" }`
User not found	404	`{ "error": "Not Found", "message": "User not found" }`
Organization not found	404	`{ "error": "Not Found", "message": "Organization not found" }`
Duplicate email	409	`{ "error": "Conflict", "message": "Email already exists" }`
Invalid request	400	`{ "error": "Bad Request", "message": "Invalid input" }`
Server error	500	`{ "error": "Internal Server Error", "message": "Something went wrong" }`

9. Security Measures

App-JWT Security

Signature: HS256 using the shared BETTER_AUTH_SECRET
Expiration: 7 days (APP_TOKEN_TTL in services/auth/api.ts)
Storage: HttpOnly cookie for web; secure storage on mobile
Transport: HTTPS only (enforced in production)

Token Revocation

A long TTL is safe because immediacy comes from server-side revocation, not a short expiry (services/auth/revocation.ts):

On any status, role, or permission change, a per-user marker authInvalidBefore:<userId> = now is written to Redis.
Both the Bun middleware and Go’s better_auth_validator.go reject any JWT whose iat predates the marker. Every outstanding token for that user dies at once.
The marker TTL is 8 days — one day longer than the longest-lived token — so it self-expires without unbounded growth.
A companion auth_versions table tracks a per-user version counter.

Error-handling policy is deliberately divergent between the two backends: on a revocation-store error, Go fails open and Bun fails closed. This asymmetry is intentional and is explicitly excluded from the shared golden-vector contract.

Password Security

Hashing: scrypt (Better Auth default), stored in accounts.password
Storage: hashed only, never plaintext
Comparison: constant-time comparison to prevent timing attacks
Minimum length: 8 characters (Better Auth default)

Database Security

Access Control: PostgreSQL user permissions restrict access
Connection: SSL/TLS encryption in production
Secrets: Environment variables, not hardcoded

Multi-Tenancy

Isolation: Organization data accessed via organizationId in context
RBAC: Role-based access control at organization level
Audit: Member actions logged for compliance

10. Migration from Old Auth System

Key Changes

No NATS User Sync: Previously, users were synced via NATS events. Now they’re queried directly from PostgreSQL.
No Local User Table (Go): Go backend no longer creates/maintains its own users table.
Direct Query Pattern: Go backend queries Better Auth tables (users, members, organizations).
Centralized Mutations: All write operations go through Better Auth API on Bun.

For Backend Developers

Use PermissionService for authorization checks
Query users/orgs using the provided repositories
Role changes reach Go through token revocation plus the 5-minute cache TTL — there is no NATS invalidation (see Section 6.2)
Permission checks are fast (cached, with a < 50ms latency target)

For Frontend Developers

Update user/org creation calls to use Better Auth API
Read operations remain unchanged (Go backend still provides queries)
Handle new permission error responses (403)

11. Monitoring & Troubleshooting

Key Metrics to Monitor

Auth latency: time to verify a JWT and fetch user data
Cache hit rate: permission cache effectiveness
Redis availability: the revocation marker store — Bun fails closed without it
Database query performance: user/org queries should be < 50ms

Common Issues

Issue	Cause	Solution
”Token expired” errors	App-JWT expires after 7 days	Re-exchange the session at `POST /api/v1/auth/app-token`
”Unauthorized” on a valid token	Signature mismatch	Verify `BETTER_AUTH_SECRET` matches on both backends
401 immediately after a role change	Revocation marker fired — this is intended	Re-mint the app-token; the new one carries fresh claims
Role change not taking effect	Gate trusts the token, or the 5-min cache has not expired	Re-mint the token (`RequireJWTRole` does no DB lookup); wait out the TTL
Newly promoted landlord gets 403	Current JWT still carries the old role	Honour `token_refresh_required: true` and re-mint
Stale permissions across replicas	Per-process in-memory cache, no shared invalidation	Wait for the 5-minute TTL; do not expect NATS to clear it
”User not found” after signup	Database replication lag	Add retry logic with exponential backoff
`JWK must be an object` on startup	Private-key encryption disabled against a shared `jwks` table	Never env-gate `disablePrivateKeyEncryption`

12. API Endpoints Summary

Authentication (Bun)

POST   /api/auth/sign-up              Sign up new user      (returns a SESSION)
POST   /api/auth/sign-in              Sign in               (returns a SESSION)
POST   /api/auth/sign-out             Sign out current user
GET    /api/auth/token                PowerSync sync token  (asymmetric, JWKS)
GET    /api/auth/jwks                 Public keys for the sync token

POST   /api/v1/auth/app-token         Exchange a live SESSION for the HS256 app-JWT

POST /api/auth/refresh-session does not exist — earlier revisions of this document listed it. To get a fresh app-JWT, re-run the /api/v1/auth/app-token exchange against a live session.

User Management (Bun - Admin Plugin)

POST   /api/auth/admin/create-user    Create new user
POST   /api/auth/admin/set-role       Change user's platform role
GET    /api/auth/admin/list-users     List all users
GET    /api/auth/admin/get-user       Get user details
POST   /api/auth/admin/remove-user    Delete user

Organization Self-Service (Bun — `services/organizations/api.ts`)

Mounted at /api/v1/organizations. Requires an authenticated org member.

GET    /api/v1/organizations/me                                  My organizations
GET    /api/v1/organizations/:orgId                              Read one org
PATCH  /api/v1/organizations/:orgId                              Update org details
GET    /api/v1/organizations/:orgId/members                      List members
PATCH  /api/v1/organizations/:orgId/members/:memberId            Update member role
DELETE /api/v1/organizations/:orgId/members/:memberId            Remove member
GET    /api/v1/organizations/:orgId/members/:memberId/permissions Resolve permissions
POST   /api/v1/organizations/:orgId/invitations                  Invite member
GET    /api/v1/organizations/:orgId/invitations                  List invitations
DELETE /api/v1/organizations/:orgId/invitations/:invitationId    Revoke invitation
POST   /api/v1/organizations/:orgId/leave                        Leave the organization
GET    /api/v1/organizations/:orgId/audit                        Read audit trail
POST   /api/v1/organizations/:orgId/audit/cleanup                Prune audit trail

Custom roles (createRolesAPI) and teams (createTeamsAPI) mount on the same prefix. Organization creation goes through the Better Auth organization plugin, served by the catch-all /api/auth/* handler.

Platform Admin (Bun — `services/admin/api.ts`)

Mounted at /api/v1/admin/organizations, every route behind adminOnlyMiddleware. Full CRUD over any organization, its members, custom roles, invitations, and audit log.

Rental Platform Role (Go)

POST   /api/rental/landlord/promote    Promote the session account to 'landlord'
                                       → returns { role, token_refresh_required: true }

User & Organization Queries (Go)

GET    /api/v1/users/:id                      Get user by ID (read-only)
GET    /api/v1/organizations/me               Get current org (read-only)
GET    /api/v1/organizations/me/members       List org members (read-only)

References

Module Access Control — which user reaches which module
Bun Backend Authentication
Go Backend User Module
Go Backend Organization Module
Permission Service Integration
CLI Auth Architecture — device flow and API keys
ADR-0006 — Better Auth read-only consumer (Go never writes roles)

Source of truth

Concern	Path
Better Auth schema	`backend/bun/packages/auth-adapter/schema.ts`
Better Auth wiring	`backend/bun/apps/monolith/src/config/di-container.ts`
App-token exchange	`backend/bun/apps/monolith/src/services/auth/api.ts`
Token revocation	`backend/bun/apps/monolith/src/services/auth/revocation.ts`
Cache invalidation	`backend/bun/apps/monolith/src/services/cache/cache-invalidator.ts`
Go token validation	`backend/go/internal/api/http/middleware/better_auth_validator.go`
Permission resolution	`backend/go/internal/modules/organizations/application/usecase/permission_service.go`
Cross-process contract	`contracts/auth/role-revocation-vectors.json`

​Authentication Flow with Better Auth Plugins

​System Architecture Overview

​1. User Registration Flow

​Step-by-Step Process

​1.1 User Initiates Sign-Up

​1.2 Bun Backend Processes Registration

​1.3 Frontend Receives the Session

​2. User Login Flow

​Step-by-Step Process

​2.1 User Initiates Sign-In

​2.2 Bun Backend Verifies Credentials

​2.3 Frontend Receives the Session

​3. App-Token Exchange (Session → JWT)

​4. Authenticated Request Flow (Go Backend)

​Step-by-Step Process

​4.1 Frontend Makes Authenticated Request

​4.2 Bun Backend Verifies JWT (if applicable)

​4.3 Go Backend Processes Request

​5. Organization Management Flow

​5.1 Create Organization

​5.2 Invite Member to Organization

​5.3 Change a Member’s Role

​6. Permission Query Flow (Go Backend)

​6.1 Authorization for Protected Operations

​6.2 Cache Invalidation Flow

​7. Role Hierarchy & Permissions

​Platform Roles (Better Auth Admin Plugin)

​Organization Roles (Better Auth Organization Plugin)

​8. Error Handling

​Common Error Scenarios

​9. Security Measures

​App-JWT Security

​Token Revocation

​Password Security

​Database Security

​Multi-Tenancy

​10. Migration from Old Auth System

​Key Changes

​For Backend Developers

​For Frontend Developers

​11. Monitoring & Troubleshooting

​Key Metrics to Monitor

​Common Issues

​12. API Endpoints Summary

​Authentication (Bun)

​User Management (Bun - Admin Plugin)

​Organization Self-Service (Bun — services/organizations/api.ts)

​Platform Admin (Bun — services/admin/api.ts)

​Rental Platform Role (Go)

​User & Organization Queries (Go)

​References

​Source of truth

Authentication Flow with Better Auth Plugins

System Architecture Overview

1. User Registration Flow

Step-by-Step Process

1.1 User Initiates Sign-Up

1.2 Bun Backend Processes Registration

1.3 Frontend Receives the Session

2. User Login Flow

Step-by-Step Process

2.1 User Initiates Sign-In

2.2 Bun Backend Verifies Credentials

2.3 Frontend Receives the Session

3. App-Token Exchange (Session → JWT)

4. Authenticated Request Flow (Go Backend)

Step-by-Step Process

4.1 Frontend Makes Authenticated Request

4.2 Bun Backend Verifies JWT (if applicable)

4.3 Go Backend Processes Request

5. Organization Management Flow

5.1 Create Organization

5.2 Invite Member to Organization

5.3 Change a Member’s Role

6. Permission Query Flow (Go Backend)

6.1 Authorization for Protected Operations

6.2 Cache Invalidation Flow

7. Role Hierarchy & Permissions

Platform Roles (Better Auth Admin Plugin)

Organization Roles (Better Auth Organization Plugin)

8. Error Handling

Common Error Scenarios

9. Security Measures

App-JWT Security

Token Revocation

Password Security

Database Security

Multi-Tenancy

10. Migration from Old Auth System

Key Changes

For Backend Developers

For Frontend Developers

11. Monitoring & Troubleshooting

Key Metrics to Monitor

Common Issues

12. API Endpoints Summary

Authentication (Bun)

User Management (Bun - Admin Plugin)

Organization Self-Service (Bun — `services/organizations/api.ts`)

Platform Admin (Bun — `services/admin/api.ts`)

Rental Platform Role (Go)

User & Organization Queries (Go)

References

Source of truth