Stripe's Permission Problem
Stripe has exactly one permission model: you have the API key, or you don't. There's no concept of "this person can view invoices but not issue refunds" or "this person can see subscription data but not customer emails."
For a solo founder, that's fine. For a team of 15 with support agents, account managers, and finance people all needing different levels of billing access — it's a serious problem.
The Four Roles
We designed Agent Billy's RBAC system around four distinct roles, each mapping to real-world team responsibilities:
Viewer
Can see: Dashboard metrics, customer lists, subscription summaries, invoice history, charge history.
Cannot do: Anything that modifies data. No refunds, no cancellations, no customer edits.
Use case: Support agents who need to look up a customer's billing status. Finance team members pulling reports. Executives reviewing MRR.
Operator
Can see: Everything a Viewer can see, plus detailed customer records and payment method info (last 4 digits only).
Can do: Update subscription quantities, apply coupons, extend trials.
Cannot do: Issue refunds, cancel subscriptions, delete customers.
Use case: Account managers who need to adjust plans. Sales team modifying trials.
Manager
Can see: Everything.
Can do: Everything an Operator can do, plus issue refunds (with amount limits), cancel subscriptions, and void invoices.
Cannot do: Change API keys, modify team permissions, access audit logs for other users.
Use case: Senior support leads, billing managers, team leads.
Admin
Can see: Everything, including full audit logs.
Can do: Everything, including team management, API key rotation, and permission changes.
Use case: The billing owner. Usually one or two people per organization.
How Enforcement Works
RBAC enforcement happens at three layers:
Layer 1: UI
The dashboard hides buttons and pages that the user's role doesn't allow. A Viewer literally never sees a "Refund" button. This is the friendliest layer — no confusing error messages, just a clean interface scoped to your permissions.
Layer 2: API
Every API endpoint checks the user's role before executing. Even if someone crafts a direct API call, the server rejects it if the role doesn't permit the action. This is the enforcement layer.
Layer 3: Stripe Restricted Key
The restricted API key connected to each role has permissions that match the role's capabilities. Even if layers 1 and 2 somehow fail, the Stripe API itself will reject unauthorized operations.
The Audit Trail
Every action in Agent Billy is logged: who did it, what they did, when, and from where. Managers can review their team's activity. Admins can review everyone's.
This matters for compliance, but it also matters for trust. When you give five people billing access, you need to know what happened when a customer reports an unexpected refund.
Why Not Just Use Stripe's Team Feature?
Stripe does offer team access on their dashboard, but it requires every team member to have a Stripe account, and the permission model is coarse-grained (developer vs. analyst vs. administrator). Agent Billy's roles are designed specifically for billing operations, with granularity that maps to actual team workflows.