Documentation

Admin manual

Last updated · June 2026

1. Admin overview

This guide is for workspace owners and admins. It covers the controls that affect every user in the tenant — billing, branding, and invites.

  • Owner — root account, manages billing, can demote / delete admins.
  • Admin — manages users, branding, categories, and integrations.
  • Accountant — full read/write on financial data, no admin controls.
  • Viewer — read-only access to dashboards and reports.

2. Workspace & branding

The workspace is your tenant — the isolation boundary for every other resource. Branding carries through to every exported report.

  1. 01
    Open Settings → Workspace
    Update the workspace name. This appears as the title on every report PDF / Excel cover.
  2. 02
    Pick a brand color
    Hex color — used for emphasis blocks (Net Income, Total Liabilities + Equity, Net Change in Cash) and the reconciliation header.
  3. 03
    Upload a logo
    Up to 2 MB, base64-encoded and stored alongside your tenant record. The logo appears at the top of every PDF cover.
Reset to defaults
Clear both the brand color and logo to restore Financials Ready's default navy palette across all exported reports.

3. Users, roles & invites

Add accountants, bookkeepers, and stakeholders by invite. Every invite is single-use and expires.

  1. 01
    Open Team
    Sidebar → Team.
  2. 02
    Click 'Invite user'
    Pick a role (Admin, Accountant, Viewer). Owners cannot be invited — they are created at workspace signup.
  3. 03
    Share the invite link
    Copy the generated URL and send it to the recipient. The link works once and self-expires after the configured TTL.
  4. 04
    Manage existing users
    Toggle role or deactivate from the team table. The owner cannot be deactivated.
Team-member limits
Your plan caps the number of active team members. If you hit the cap, deactivate an inactive user or upgrade your plan before issuing a new invite.

Guided-tour state per user

Every user row carries a tour_state object on their users doc: { variant, completed, dismissed, last_step_index, updated_at }. The variant is derived from role (owner/admin → owner, accountant → accountant, viewer → viewer, client → client), so a role change automatically swaps which deck of steps plays next time the user hits “Take the tour”.

  • Read: GET /api/tour-state. Writes a fresh default (completed=false, dismissed=false, last_step_index=0) if the user has never seen it.
  • Update: PATCH /api/tour-state with any subset of {completed, dismissed, last_step_index}. The frontend writes on every Next click so progress is resumable across devices.
  • Reset for a user you want to re-onboard: hit PATCH /api/tour-state with {"completed": false, "dismissed": false, "last_step_index": 0}and ask them to clear the ll_tour_seen_<userId> key from localStorage (or sign in from a different browser) — the tour will auto-launch on their next login.
  • Clients get a separate 4-step deck focused on the upload portal. The route is whitelisted in CLIENT_ALLOWED_EXACT so client-role JWTs can still save progress.

4. Billing & plan limits

Billing is handled via Stripe Checkout. Plans differ in bank account count, seat count, and statement history depth.

  • Starter — $29/mo: 1 bank account, 3 months history, 1 seat.
  • Pro — $79/mo: 5 bank accounts per client workspace (buy more at $3/mo), 60 months history, 5 team members (buy more at $10/mo up to 24 total), up to 25 client workspaces.
  • Business — $199/mo: unlimited bank accounts per client workspace, 60 months, 25 team members, unlimited client workspaces.
  1. 01
    Open Billing
    Sidebar → Billing.
  2. 02
    Click 'Upgrade plan'
    Stripe Checkout opens in a new tab. After payment, your plan and limits update automatically.
  3. 03
    Download invoices
    Past payment_transactions are listed in the billing screen — click any row to view.
Failed payments
If Stripe declines a charge, your plan stays active until the end of the current period. We mark the workspace 'past_due' and email the owner.
Webhook signature validation
Every incoming Stripe webhook is signature-verified using STRIPE_WEBHOOK_SECRETfrom backend/.env. In production (with a real sk_live_* key), any request missing the Stripe-Signature header is rejected with a 400, and any bad signature is caught by the SDK's construct_event. In dev mode (sk_test_emergent) signatures are accepted permissively — this is intentional so local proxy replays work. Set the real secret in .env and restart the backend before pointing production traffic at the webhook endpoint.

5. Custom categories

The default category list covers most general-purpose businesses. Add domain-specific categories per workspace to match your chart of accounts.

  1. 01
    Open Settings → Categories
    Review the default list. Defaults cannot be removed but you can add custom ones below.
  2. 02
    Add a new category (Settings)
    Name and pick a group (Income, COGS, Expense, Other). The group decides which report bucket the category contributes to (e.g. an 'Income' custom category feeds Revenue on the P&L).
  3. 03
    Add a new category (Transactions page)
    Users can also create categories inline: on the Transactions page, click the + button next to the category filter, name the category, pick a group, save. It appears in every dropdown immediately and is tenant-scoped (every teammate sees it).
  4. 04
    Bulk re-categorize legacy data
    Use the bulk re-categorize action on the Transactions screen. Select rows via checkboxes, pick the new category from the bulk-action bar, click Apply.
  5. 05
    Bulk import via CSV
    The Transactions page 'Import CSV' button lets users paste or upload up to 500 rows with per-row category or a bulk 'Assign category' bar in the preview. Duplicates on (bank, date, description, amount) are auto-skipped. Column mapping is saved per bank in browser localStorage.
  6. 06
    Delete or bulk-delete rows
    The trash icon on any Transactions row (or the bulk-action bar's Delete button) removes the row(s) permanently. Reconciled rows are protected — un-reconcile first. Deleting also decrements the parent statement's counter.

7. Platform admin (cross-tenant)

Platform admin is a SaaS-wide superuser role for Financials Ready staff. Anyone whose email is listed in PLATFORM_ADMIN_EMAILS (server env, comma-separated) gets is_platform_admin=true on startup, plus a "Platform admin" link in the sidebar.

  • 8-KPI control room — total tenants, users, active subs, MRR, trial subs, bank accounts, statements, txns (last 30d).
  • Five tabs — Tenants, Users, Login activity, Impersonation audit, Comped accounts. All of them respect your filters and support CSV export where applicable.
  • Searchable tenant table with inline editors for plan (starter/pro/business) and subscription status. Flip a tenant to comped (free) by clicking "Set free" on the row — a modal demands a category (Partner / Beta tester / Support credit / Internal / Other) + a free-text reason. The grant appears in the Comped accounts tab with filters by category and CSV export for quarterly reviews. Revoke it with one click to flip the tenant back to active.
  • Tenant detail drawer — click any row to open 4 tabs: Overview (KV + counts), Users (with platform-admin badges), Billing (Stripe transactions), Audit log (timeline of plan changes, impersonations, flag events).
  • Users tab (bulk + single) — checkboxes on every row + a select-all. Toolbar lets you bulk-deactivate, bulk-reactivate, or bulk-reset-passwords with per-row results (partial failures surface individually, e.g. "would leave tenant without an active owner"). Single-user actions (view, edit, delete, impersonate, reset password) remain on each row.
  • Login as tenant / user — mints a 15-minute JWT marked impersonated=true. A modal demands a short reason (min 3 chars) before the session starts. Every impersonation is logged to the Impersonation audit tab (actor, target, tenant, reason, TTL, time) with filters for actor email, target email, and time window.
  • Login activity — per-tenant daily login counts rendered as inline SVG sparklines over the last 7 – 90 days. Dormant tenants (no login in 30+ days) get a red "Dormant" badge; use the "Dormant only" filter to spot workspaces at risk of churn.
  • Export tenant data — generates an AES-256 password-protected ZIP of every record scoped to the tenant (12 collections + manifest + README). Password returned in X-Export-Password response header AND persisted in the audit log so a future admin can re-derive it. Used for GDPR Art. 15 / CCPA §1798.110 data-subject access requests.
Everything is audited
Every patch, impersonation, export, lock/unlock, and comp grant/revoke is appended to the admin_audit collection with actor email + payload diff. The Impersonation audit tab and Comped accounts tab are specialized views over the same append-only log.

8. Compliance (close periods, audit)

Two features in Settings give owners and admins the tools auditors look for during month-end close.

Closed periods (period lock)

  • Lock a month in Settings → Closed periods (or in one tap via the Close month button on the Reconciliation page, which defaults to the previous calendar month).
  • Once locked, any PATCH or DELETE on a transaction dated inside that month returns 409 period_locked and the UI shows a lock icon on the row. Only the notes field remains editable, so follow-up flagging still works even on closed months.
  • Owner / admin can re-open from the same card — every unlock writes an admin_audit entry with the actor, year, month, and timestamp.
  • Each lock stamps who closed it, when, and an optional reviewer note. Re-locking an already-locked month is idempotent (refreshes the note) so a scheduled job can safely re-run.

Flag follow-up templates

  • Manage reusable follow-up reasons in Settings → Flag follow-up templates. Four defaults are seeded on first visit for every tenant: Awaiting receipt, Possible duplicate, Needs re-categorization, Confirm with client.
  • Reorder with the arrow controls, inline-edit the pencil icon, or delete templates that don't apply to your workflow. Changes are tenant-scoped.
  • Templates surface as one-click chips in the Reconciliation verify panel's Flag modal. Reviewers can tap a chip (populates the note field) or type something custom.

Opening-balance audit

  • Every PATCH that changes bank_accounts.opening_balance appends a row to opening_balance_history with previous_value, new_value, delta, actor id/name/email, and timestamp.
  • Read-only history endpoint: GET /api/bank-accounts/{id}/opening-balance-history. Surfaced in the UI as the clock icon beside the Reconciliation page's opening balance → opens a drawer with every mutation and a +/- delta badge.
  • Suggestion endpoint: GET /api/bank-accounts/{id}/opening-balance-suggestionpeeks at the earliest parsed statement's opening_balance field; returned to the UI as the "Use statement's opening balance" one-click chip. Reduces onboarding setup error — the number auditors look at first.

Verify audit trail

Every is_reconciled=true patch stamps reconciled_by, reconciled_by_name, and reconciled_at on the transaction. The Verify panel surfaces this inline under each row ("Verified by Priya · 03 Feb 2026") and in a hover tooltip on the check icon. Un-verifying clears the stamp so the next review is attributed cleanly.

Opening balance edits bypass the lock
Opening balance is a per-account static value, not dated to a specific month, so changing it is allowed even if months are locked. It will however re-shift computed closing balances — review before changing on a reviewed ledger.

9. Demo tenants & background crons

Financials Ready exposes a public zero-signup demo endpoint used by the landing-page "Try the live demo" button, plus two APScheduler cron jobs that keep the database healthy. This section is for platform admins who need to reason about these background writes.

  • POST /api/auth/demo — unauthenticated. Mints a tenant with id = demo-<12-hex> , an owner user (email demo-<12-hex>@financialsready.app, random 32-byte password), two bank accounts (checking + savings), two statements, ~400 seeded transactions over 12 months (mobile-tuned volume), 6 invoices (paid/partial/sent/overdue/draft), 1 recurring invoice template, and 1 active payment plan. Returns the same{ token, user, tenant } payload as /auth/login. The tenant is placed on the business plan so all features are unlocked for the trial.
  • Rate limit: 5 demos per source IP per hour (sliding window, in-memory). Exceeding the limit returns HTTP 429 with a friendly retry-after message. Because the counter is in-process, the effective per-host limit is 5 × N-workers — fine for a preview button, but consider a Redis-backed limiter before a serious marketing launch.
  • Daily 3am UTC — dormant-user deactivation. Any non-owner, non-platform-admin user whose last_login_at is older than DORMANT_USER_DAYS (default 90) is flipped to is_active=false. An admin_audit row with action user.auto_deactivate is written per user. Owners are exempt so a tenant is never accidentally locked out.
  • Daily 4am UTC — demo tenant cleanup. Every tenant whose id starts with demo- and whose created_atis older than 24 hours is purged along with ALL child rows: users, bank accounts, statements, transactions, memberships, custom categories, bank connections, and prior audit entries. A final demo_tenant.cleanup audit row is written for each purge.
  • Daily 5am UTC — recurring rules materialisation. Every active row in recurring_rules whose next_run is today or earlier is materialised into a real transactions row (with is_manual=true) and the schedule is advanced by its cadence. If the current next_run's YYYY-MMappears in the rule's skip_periods, the row is advanced without creating a transaction (pause window). Duplicate protection: if a matching (bank, date, description, amount) row already exists (e.g. a statement upload created it first), the schedule still advances but no duplicate is inserted. Backfill loop caps at 24 iterations per rule to avoid runaway loops on malformed dates.
  • Weekly Monday 9am UTC — upload reminder push. Sends a web-push nudge to any owner whose tenant hasn't uploaded a statement in the last 30 days. Respects each user's push-subscription opt-in.
Manually cleaning up mid-day
Need to purge demos before the 4am cron? Run python -c "from routes_demo import cleanup_expired_demo_tenants; import asyncio; asyncio.run(cleanup_expired_demo_tenants())"from /app/backend to fire it on demand.
Demo users can't log in
The demo user's password is secrets.token_urlsafe(32) — effectively unguessable. Demos are strictly session-bound: once the returned JWT expires or the tenant is purged, that user is inaccessible. This is intentional.

9. Data lifecycle & deletes

Cascade rules to know about before you delete anything:

  • Deleting a bank account deletes all related statements and transactions.
  • Deleting a statement deletes all transactions that originated from it.
  • Deleting a transaction is now surfaced directly on the Transactions screen — via a per-row trash icon or a bulk-action bar "Delete" button. The parent statement's transaction_count is decremented automatically so exports and dashboards stay in sync.
  • Reconciled transactions are protected from deletion — the endpoint returns HTTP 409 and the UI disables the trash icon with a "Un-reconcile first" tooltip. This is a safety guard so a closed period never silently changes underneath you.
  • Bulk delete silently skips reconciled rows in the selection and reports them via skipped_reconciled — the un-reconciled rows are still deleted.
  • Deleting a user revokes their token and removes them from the team table; transactions they edited remain.
  • Deleting a tenant (workspace) is a support-only action and cannot be self-served.
  • Demo tenants (id prefixed demo-) are auto-purged after 24h by the daily 4am cron — see section 8.
Backups
Deletes are immediate. We retain MongoDB backups for 7 days — email support if you need a restore.

10. Security & compliance

  • Passwords are hashed with bcrypt at cost factor 12; we never store plaintext.
  • JWTs are signed with HS256 using the per-deployment JWT_SECRET. Tokens expire after 24h of inactivity.
  • Stripe API keys, Teller MTLS keys, and the LLM key live in backend/.env — never in client code.
  • Tenant isolation is enforced at the database query layer: every read and write is filtered by tenant_id.
  • Webhook signatures (Teller, Stripe) are verified before any state mutation occurs.

11. Troubleshooting

  • Statements stuck in 'parsing' — check the backend supervisor logs for parser errors. Restart with sudo supervisorctl restart backend if needed.
  • AI categorization returning 'Uncategorized' — your Emergent LLM key may be out of credit. Check Settings → Universal Key in the Emergent admin console.
  • Stripe checkout opens but plan never updates — webhook signature failing. Check the webhook URL in Stripe matches your deployed backend AND that STRIPE_WEBHOOK_SECRET in .env matches Stripe's dashboard value. See section 4.
  • Statement preview says "No date column detected" — your CSV headers don't include a recognized date keyword. Cancel the preview, rename the column to Date or Posted Date, re-export from your bank, and try again.
  • Trash icon disabled on a transaction — the row is reconciled. Toggle the reconciled checkbox off first, then the trash icon becomes active.
  • "Try the live demo" returns 429 — you've exceeded the per-IP demo rate limit (5/hour). Wait, or bump DEMO_RATE_LIMIT in routes_demo.py. See section 8.
  • PDF export looks wrong — try clearing branding (Settings → reset color & logo) to isolate whether the issue is brand-color or layout-related.
Still stuck?
Email support@financialsready.app with the workspace ID (Settings → Workspace) and a short description. A finance-literate engineer triages every report within hours.

13. Release notes & the What's new popup

  1. 01
    Write a release
    Platform Admin → Release notes → New release. Enter the version, title, audience (Staff, Clients or Everyone), a summary and one line per feature, with an optional link and plan label.
  2. 02
    Publish
    Drafts are invisible. Publishing shows the popup once to every user in that audience after they sign in. Unpublish hides it again.
  3. 03
    Prefilled June 2026 release
    Staff and client release notes for checks, receipts and Positive Pay are published automatically on first start.

14. Plan features: checks & receipts

  • All plans: duplicate check & charge flags, Check # column, missing check numbers, Check Register, stale checks & bulk void, receipt photos with auto-crop, matching and missing-receipt flags.
  • Pro & Business (and trials): AI receipt reading + auto-category, client receipt reminders (weekly cron + Send now), Receipt Pack PDF, Positive Pay export.
Background job
The 'receipt-reminders' platform cron runs Mondays at 9am US Eastern and calls /api/cron/receipt-reminders with WEBHOOK_CRON_SECRET. Each client gets at most one nudge per week.
Positive Pay account numbers
Full account numbers are entered by owners/admins and only ever shown masked. Treat them as sensitive.