Features

1

Authentication & Authorization

Email/Password Authentication

• User Registration (POST /auth/register)

  • Create new user account

  • Sends email verification link

  • Users cannot access features until verified

• Email Verification (GET /auth/verify-email?token=...)

  • Confirms user email address

  • Returns access and refresh tokens upon verification

  • Token expires after 24 hours

• Login (POST /auth/login)

  • Authenticate with email and password

  • Returns access and refresh tokens

  • Requires verified email

• Password Reset

  • Request reset (POST /auth/reset-password/request)

    • Sends reset link to email

  • Confirm reset (POST /auth/reset-password/confirm)

    • Sets new password using token

Google OAuth

• Google Login (POST /auth/google-login)

  • Authenticate using Google account

  • Auto-creates user if doesn't exist

  • Email is automatically verified

  • No password required

Token Management

• Refresh Token (POST /auth/refresh)

  • Exchange refresh token for new access token

  • Extends session without re-login

Super Admin System

• First user created (via FIRST_SUPERUSER env variable) has super admin privileges

• Super admins can view all tenants and their details

• Detected via JWT claims (is_super_admin: true)

2

Multi-Tenancy

Tenant Management

• Create Tenant (POST /tenants)

  • User who creates tenant becomes admin

  • Tenant gets Stripe customer ID for billing

• List User Tenants (GET /tenants)

  • Returns all tenants user belongs to

  • Includes user's role in each tenant

• Get Tenant Details (GET /tenant)

  • Fetch specific tenant information

  • Requires tenant membership

• Update Tenant (PUT /tenant)

  • Modify tenant name and description

  • Requires admin role

• Delete Tenant (DELETE /tenant)

  • Remove tenant and all associated data

  • Requires admin role

Tenant Context

• Most API endpoints require X-TENANT-UUID header

• Backend validates user has access to tenant

• Data is automatically scoped to tenant

3

Team Management

Member Management

• List Members (GET /members)

  • View all tenant members

  • Shows email and role for each member

• Change Member Role (PATCH /members/role)

  • Promote member to admin or demote admin to member

  • Requires admin role

• Remove Member (DELETE /members)

  • Remove user from tenant

  • Requires admin role

Invitation System

• Invite User (POST /invite)

  • Send invitation email to new user

  • Specify role (admin or member)

  • Creates invitation token (expires in 7 days)

  • Works for both existing and new users

• Accept Invitation (GET /invitations/{token}/accept)

  • Accept invitation and join tenant

  • If user exists, automatically adds to tenant

  • If user doesn't exist, shows registration form

• Set Password (POST /invitations/{token}/set-password)

  • New users set password via invitation flow

  • Marks invitation as accepted

  • Adds user to tenant with specified role

User Roles

• Admin: Can manage members, modify tenant, delete tenant

• Member: Can access tenant data but cannot manage team

4

Items (Example CRUD Resource)

The Items feature demonstrates a complete CRUD implementation for tenant-scoped resources.

• Create Item (POST /items)

  • Add new item to tenant

  • Fields: name, description

• List Items (GET /items)

  • Fetch all items for tenant

  • Automatically filtered by tenant

• Get Item (GET /items/{item_uuid})

  • Fetch single item details

• Update Item (PATCH /items/{item_uuid})

  • Modify item name or description

• Delete Item (DELETE /items/{item_uuid})

  • Remove item from tenant

5

Subscription & Billing

Stripe Integration

• Each tenant has a Stripe customer ID

• Subscriptions are synced via webhooks

• Supports multiple subscription plans

Subscription Plans

• Get Available Plans (GET /payments/plans)

  • Returns list of subscription plans

  • Each plan includes both monthly and annual pricing

  • Shows pricing and features

  • Frontend displays pricing toggle for monthly vs annual billing

Subscription Management

• Get Current Subscription (GET /payments/subscription)

  • Returns active subscription details

  • Shows plan type, status, billing period

  • Returns null if no subscription

• Create Subscription (POST /payments/subscription)

  • Start new subscription for tenant

  • Requires payment method

  • Creates Stripe subscription

• Update Subscription (PATCH /payments/subscription)

  • Change subscription plan

  • Prorates billing automatically

• Cancel Subscription (DELETE /payments/subscription)

  • Cancel at end of billing period

  • Sets cancel_at_period_end to true

  • Tenant retains access until period ends

• Uncancel Subscription (POST /payments/subscription/uncancel)

  • Reactivate cancelled subscription

  • Must be done before period ends

Subscription Status

• active - Subscription is active and paid

• trialing - In trial period

• past_due - Payment failed, retrying

• canceled - Subscription ended

• unpaid - Payment failed, access suspended

• inactive - No subscription

Webhook Handling

The application listens to Stripe webhooks to keep subscription data in sync:

• Subscription Events:

  • customer.subscription.created

  • customer.subscription.updated

  • customer.subscription.deleted

• Invoice Events:

  • invoice.payment_succeeded

  • invoice.payment_failed

Webhook endpoint: POST /payments/webhooks/stripe

6

Payment Methods

Payment Method Management

• Get Payment Methods (GET /payments/payment-methods)

  • List all saved payment methods

  • Shows card brand, last 4 digits, expiry

  • Indicates default payment method

• Create Setup Intent (POST /payments/setup-intent)

  • Generate client secret for Stripe.js

  • Used to collect payment method on frontend

• Add Payment Method (POST /payments/payment-methods)

  • Attach payment method to tenant

  • Requires payment method ID from Stripe

• Set Default Payment Method (PATCH /payments/payment-methods/{payment_method_id}/set-default)

  • Make payment method default for subscriptions

• Delete Payment Method (DELETE /payments/payment-methods/{payment_method_id})

  • Remove payment method

  • Cannot delete default payment method if subscription exists

7

Invoices

• Get Invoices (GET /payments/invoices)

  • Fetch all invoices from Stripe

  • Shows amount, status, date, plan

  • Not stored in local database

• Download Invoice (GET /payments/invoices/{invoice_id}/download)

  • Get invoice PDF URL

  • Redirects to Stripe-hosted PDF

8

Super Admin Dashboard

Super admins (first user created) have access to administrative features:

• View All Tenants (GET /super-admin/tenants)

  • List all tenants in the system

  • Shows member count, subscription status

  • Provides tenant metrics

• View Tenant Details (GET /super-admin/tenants/{tenant_uuid})

  • Detailed view of any tenant

  • Member list with roles

  • Subscription information

  • Creation date and activity

9

Frontend Features

Dashboard

• View current tenant information

• Quick access to all features

• Tenant switcher (if user belongs to multiple tenants)

• Onboarding modal for new tenants

Members Page

• View all team members

• Invite new members via email

• Change member roles

• Remove members from team

Items Page

• CRUD interface for items

• Modal-based create/edit forms

• Tenant-scoped data

Subscription Page

• Toggle between monthly and annual billing

• View current subscription details

• Upgrade/downgrade plans

• Manage payment methods

• View billing history

• Cancel/reactivate subscription

• Pricing Display:

  • Always shows price per month for easy comparison

  • Annual plans show monthly equivalent with total annual cost

  • Example: "$8/month (billed $96 annually)"

Settings Page

• Edit tenant information

• Manage tenant settings

• Delete tenant (admin only)

Admin Dashboard (Super Admin Only)

• View all tenants in system

• Click through to tenant details

• Monitor system-wide metrics