Skip to content
Bloqr AI Bloqr AI

Authentication & Authorization

Switch to Zen Mode

Authentication & Authorization

The bloqr-backend uses Better Auth as its sole authentication provider. Better Auth runs entirely within the Cloudflare Worker, backed by Neon PostgreSQL via Cloudflare Hyperdrive and the Prisma ORM. No third-party auth service is required at runtime.

Documentation

DocumentAudienceDescription
Bootstrap RunbookOperatorsStep-by-step: first admin setup, smoke test, API key creation, Postman config
Better Auth User GuideAll usersSign-up, sign-in, 2FA, session management, API keys
Better Auth Admin GuideOperatorsUser management, banning, secret rotation, migrations
Better Auth Developer GuideDevelopersPlugin catalogue, adapter swapping, custom providers
Developer GuideDevelopersArchitecture overview, IAuthProvider interface, bindings
Auth Provider SelectionAllHow provider selection works and how to extend it
Configuration GuideOperators / DevOpsEnvironment variables, secrets, and deployment
Better Auth Prisma SetupDevelopers / DevOpsPrisma adapter, Neon, and Hyperdrive configuration
Social ProvidersOperatorsGitHub and Google OAuth setup
API AuthenticationAPI ConsumersHow to authenticate API requests programmatically
Postman TestingDevelopers / API ConsumersPostman setup for authenticated API testing
Admin AccessOperatorsAdmin endpoint protection and dashboard access
Cloudflare AccessOperators / DevOpsCloudflare Zero Trust Access for admin routes
CLI AuthenticationCLI Users / DevOpsCLI authentication with queue endpoints
Email ArchitectureDevelopers / OperatorsHybrid email delivery: Resend (auth critical) + CF Email Service REST (transactional), provider selector, flows, env setup
ZTA Review FixesDevelopersZTA hardening: telemetry, rate-limit, schema, admin fixes
Removing Anonymous AccessAllMigration plan for mandatory authentication

Deprecated (historical reference only): Clerk Setup · Clerk + Cloudflare Integration · Migration: Clerk → Better Auth

Architecture Overview

flowchart LR
    FE["Angular Frontend\n(BetterAuthService)"]
    W["Cloudflare Worker\n(Auth Middleware)"]
    PG[("Neon PostgreSQL\nvia Hyperdrive\n(users, sessions, accounts)")]

    FE -->|"Session cookie\nor Bearer token"| W
    W -->|"Session + user lookup\nvia Prisma + Hyperdrive"| PG

    subgraph W["Cloudflare Worker — Auth Chain"]
        direction TB
        AK["1. API key verify\nBearer blq_..."]
        BA["2. Better Auth session verify\ncookie or Bearer token"]
        AN["3. Anonymous fallback"]
        TE["Tier enforcement"]
        SE["Scope enforcement"]
        RL["Rate limiting"]
        AK --> TE
        BA --> TE
        AN --> TE
        TE --> SE
        SE --> RL
    end

Authentication Methods

The system supports three authentication methods:

  1. Better Auth session — Cookie or bearer session token. Created on sign-up/sign-in. Supports email+password and GitHub OAuth. Active when a valid session exists in the database.

  2. API key — Long-lived programmatic access key (blq_ prefix). Created via the API keys dashboard. Verified by hashing and database lookup on every request.

  3. Anonymous — No credentials. Lowest rate limits. Access to public endpoints only.

Tier System

TierRate LimitDescription
anonymous10 req/minUnauthenticated — public endpoints only
free60 req/minRegistered user — standard access
pro300 req/minPaid subscriber — higher limits
adminUnlimitedAdministrator — full system access

Tiers are resolved from the database user.tier field on every request. They are never trusted from JWT claims (Zero Trust principle).