A SaaS product can begin with a user record, a plan name, and a paid flag. That model answers a useful question: should this account be allowed into the paid product? It becomes less useful when the purchaser is a company and the people using the software are a changing group.
Consider a hypothetical customer buying access for 100 people. Some need analytics, some need exports, and a smaller group needs advanced reporting. The agreement starts next month and ends a year later. Departing employees must be replaced without buying another contract. A customer administrator should manage distribution, while the application's backend still makes authorization decisions.
None of those requirements is simply another value for paid. They introduce relationships, capacity constraints, time, and delegated authority. This guide develops a practical architecture for that transition, then shows how Business Mode implements the model. The architecture is useful whether you build the licensing layer yourself or integrate dedicated infrastructure.
1. Separate the questions before designing the tables
Authentication asks, "Who is this user?" Billing asks, "What did the customer pay for?" Licensing asks, "What may this organization distribute, to which users, under which constraints?" Runtime authorization asks the final question: "May this user use this capability now?"
These systems exchange information, but one should not silently substitute for another. A valid session does not prove that a company purchased advanced reporting. A paid invoice does not identify which employees should receive it. An allocation record does not prove that its underlying agreement is still valid.
Write those questions into the design before choosing services or table names. Give each answer an owner. Your identity system owns the user and session. Your commercial workflow interprets the purchase. A licensing layer records the resulting rights and allocations. Your application enforces the current access decision at the feature boundary.
That separation also makes support questions answerable. "The user can sign in but cannot export" is no longer a contradiction. Identity succeeded; the next investigation concerns the capability and its current sources of access.
2. Keep authentication in the application
The licensing layer needs a reliable way to refer to a customer user, not another copy of the user's password, profile, or session. A stable external user identifier provides that connection. Your backend derives it from the authenticated account rather than trusting an arbitrary identifier submitted by a browser.
Email is often unsuitable as the durable join key. A person can change email without becoming a different user. Conversely, an email address used for invitation delivery is not automatically evidence of the application's account identity. Treat the mapping as an explicit integration decision.
Keep the scope of that identifier clear. An ID may be unique within one application or integration project without being globally unique. Include that boundary in lookups and uniqueness rules. Avoid silently normalizing, trimming, or lowercasing opaque identifiers in the licensing layer; doing so can merge identities your application considers different.
Administrative identity is a separate concern. Someone authorized to distribute a company's seats needs a human authorization workflow, but that does not require every customer end user to become an account in the licensing control plane.
3. Map billing into commercial rights explicitly
A billing provider handles payments, subscriptions, and invoices. Those records describe financial events and agreements. Turning them into product access still requires decisions: when does access begin, which capabilities are included, how much capacity is distributable, and what happens when the commercial arrangement changes?
Do not scatter those decisions across payment-event handlers and feature gates. Define a mapping from the commercial agreement to the licensing state your application uses. The mapping might create a license, provision replacement rights, or change supported capacity. Its behavior should be reviewable independently of payment collection.
Some sales may arrive through a subscription flow; others may involve an operator recording an agreement. The access model should not require every commercial path to impersonate the same payment event. Nor should the frontend infer the entire entitlement model from a billing provider's plan identifier.
Keep reconciliation in mind. If financial and licensing state disagree, operators need to inspect both and identify the missing transition. A successful payment webhook is evidence of an event, not proof that every downstream access change has completed.
4. Make the customer organization a durable boundary
A B2B customer organization represents the company receiving access. It should survive changes to its users, administrators, name, and individual licenses. Making the first employee's user account stand in for the company creates awkward ownership transfers later.
A durable organization record gives licenses and allocations a common home. An optional external customer identifier can connect it to records in your application or commercial system. Treat names as presentation and identifiers as integration references; two companies can share a display name without being the same customer.
The organization also provides an authorization boundary for customer administrators. A person permitted to release seats for one company should not automatically acquire authority over another company or over the provider's integration settings.
There is no requirement that every product adopt exactly the same schema. A product may already have a suitable company model. The architectural requirement is a stable boundary with explicit ownership and scope, not an additional organization table for its own sake. Business Mode Organizations are one implementation of that boundary.
5. Model capabilities independently of plan names
A condition such as if plan equals enterprise mixes two kinds of information: what the application can do and how the capability was sold. Repeating that condition across the codebase makes a packaging change an authorization-code change.
Instead, name the capabilities the application actually gates. Synthetic examples are analytics, exports, and advanced_reports. A license can include analytics and exports; another can include analytics and advanced_reports. Application code asks about the capability, not which agreement happened to include it.
Choose keys with stable meaning. Changing a capability's commercial packaging should not silently change what its key authorizes. A new capability with materially different behavior may deserve a different key rather than reusing an old one with an incompatible interpretation.
This separation does not eliminate application authorization work. Your backend must still authenticate the user, choose the appropriate capability check, and enforce the result. It does remove the need for every feature gate to understand every package name. See Entitlement concepts for Business Mode's specific key semantics.
6. Use a license to express distributable access
A commercial license connects an organization to capabilities, capacity, and validity. Together, those properties describe what the customer may distribute. The license is not the user, the payment, or the invitation used to deliver access.
Time belongs in this model. A scheduled license has not started; an active one is within its validity window; an expired one has passed its end. Revocation is a deliberate withdrawal, not merely another way of saying that the end date arrived. Design these states so operators can explain them without guessing from a collection of flags.
Capacity belongs beside validity but answers a different question. A seat limit constrains allocations on the license. A validity window constrains when its rights can authorize use. Passing one check does not imply passing the other.
Retain the meaning of historical agreements. If a license has already supplied access, changing its old capability set or dates can rewrite the explanation for past allocations. A licensing system needs a policy for which fields remain editable and when a new license is the clearer commercial action. Business Mode's License model makes those boundaries explicit.
7. Treat a seat as an allocation, not a user object
A seat assignment allocates one license to one external user. That user already exists elsewhere. Releasing the seat should not delete the customer account, break authentication, or erase the person's allocation history.
One user can legitimately hold multiple licenses in the same organization. The licenses may cover different capabilities or provide overlapping rights. A member view can aggregate those allocations for operators, but that aggregate is not a second customer-user directory.
Keep immutable assignment identities. Suppose assignment A is released and the user later receives assignment B on the same license. A delayed retry targeting A should still refer to A, not to whichever allocation is current for that user. This distinction becomes important in recovery tooling.
An allocation is also not necessarily current access. Its source license can expire while the allocation remains recorded. Management screens should make clear whether they show an unreleased seat, a historical seat, or a current authorization decision. Calling all three active users hides the very lifecycle questions the system must answer.
8. Choose provisioning around the handoff
Provisioning connects purchased access to a real user. The right mechanism depends on what the initiator knows and who should complete the handoff.
- Direct backend assignment fits when the application already knows the intended user's stable ID and can authorize the allocation immediately.
- An email invitation fits when a specific recipient needs an onboarding handoff. The recipient still authenticates in the customer application.
- A redeemable code fits a workflow that distributes or accepts a bearer credential rather than an email link.
- A customer administrator provides delegated control over supported distribution operations.
- A bulk roster fits an operator with many known external IDs who needs validation and review before allocation.
These are not interchangeable credentials. An invitation has a recipient and delivery workflow; a code has its own distribution and usage rules; an administrator has scoped human authority.
Decide whether creating a provisioning credential reserves capacity, when capacity is checked, and what repeating redemption returns. Those choices affect customer expectations and retry safety. In Business Mode, invitation creation does not reserve a seat, and historical same-user redemption is not a general seat-restoration operation. The Customer Provisioning guide covers the implementation details.
9. Preserve access provenance, then answer the current question
A hasAnySeat check is too coarse when licenses can include different capabilities, expire, or overlap. The application needs an answer for a particular user and capability at a particular time.
A useful architecture separates allocation from provenance. The assignment records who received a license; a grant records why that user receives a capability. Current authorization combines the grants that are valid now. An optimized effective-access projection can make that decision convenient to query without becoming a separate source of manually maintained rights.
This matters when two licenses grant analytics. Releasing one assignment removes its contribution. It should not remove analytics while another valid grant still supplies it. Conversely, retaining a historical allocation should not extend a time-limited grant beyond its validity.
Design the projection with reconciliation in mind: when the underlying grants change, the answer must be recomputed according to the same domain rules. Operators should be able to trace a surprising answer back to its sources. Business Mode documents this separation in Access decisions.
10. Model lifecycle transitions without erasing history
A licensing system must handle more than purchase and cancellation. Start dates, natural expiration, explicit revocation, individual release, and reassignment have different effects on allocation and access.
Natural expiration is a time boundary. A right can stop authorizing access without a destructive mutation of every related record. Release is an explicit allocation change. Revocation deliberately withdraws a license and follows that system's defined cleanup rules. Do not make a single delete operation carry all three meanings.
History is useful precisely because current state changes. It can explain which allocation supplied access, who released it, and whether a later allocation is a replacement. Preserve those distinctions in identifiers and audit records rather than trying to reconstruct them from the latest member list.
For Business Mode specifically, natural License expiry can leave unreleased assignments, member rows, and allocated usage while access is already false. Explicit License revocation removes its active allocations and grants; individual release removes only the targeted assignment's grants. The Seat lifecycle guide explains how those transitions reconcile.
11. Define the unit behind every capacity number
A licensing layer can enforce more than one capacity limit. A per-license seat limit constrains allocations on one agreement. An account-wide organization-user limit can constrain distinct allocated users across a broader commercial boundary. They are different units, not two labels for one counter.
Consider a user with seats on two licenses in the same organization. The user consumes one seat on each license. Under a distinct-organization-user model, that is one organization-user unit. The same external user allocated in two organizations can contribute two units because the organization is part of the identity being counted.
Release follows those units. Removing one of two seats can free license capacity without reducing distinct organization-user usage. The broader count decreases only when the relevant final allocation disappears. Likewise, time-limited access ending does not necessarily mean an allocation-based usage count falls.
Write these definitions down before presenting a dashboard total. In Business Mode, Workspace capacity is the provider Account's organization-user allowance, separate from each customer's License seat limit. Pricing defines the commercial capacity catalog; it should not be duplicated into integration logic as fixed numbers.
12. Use synchronization as a complement to canonical reads
An API provides commands and current-state reads. Webhooks tell another system that a supported event occurred. Audit records explain the actor and mutation provenance. A useful operational architecture needs to distinguish all three.
Signed webhooks let a receiver authenticate incoming event bytes, but the receiver still needs durable deduplication and a policy for accepting work. Retry visibility helps an operator determine whether a delivery received an acknowledgement. It does not prove that the receiver completed every downstream business task.
Events also need reconciliation. An event can be delayed or delivered more than once, and a consumer may start after earlier events occurred. Do not make successful synchronization depend on every consumer having observed an uninterrupted history from the beginning.
Use events to trigger appropriate local work or canonical-state refreshes, and use current access semantics when authorization matters. Business Mode exposes signed deliveries and diagnostics as part of its developer platform. Its Webhook guide documents the exact receiver and delivery behavior rather than promising that events eliminate state reads.
13. Make concurrent writes and uncertain outcomes explicit
Reading a count and then writing a seat is not a capacity guarantee. Two callers can observe the same remaining slot and both try to use it. The final allocation transaction must enforce the invariant against the state that actually exists when it commits.
Previews still have value. An operator can inspect a roster, correct invalid IDs, and understand likely capacity needs before sending a mutation. The preview must be described as guidance, not a reservation. A favorable preview can become stale while the operator reviews it.
Network uncertainty is another design input. A client can lose a response after a mutation commits. For a durable idempotent operation, retain the logical request and its key so a deliberate retry can recover the original outcome. Generating another key creates another attempt, not a continuation of the first.
Not every mutation has that contract. A bulk release targeting current users has different replay risk from an exact release targeting an immutable assignment ID. Recovery must follow the operation, error code, and canonical state. Business Mode's Idempotency and Errors & recovery pages make those distinctions explicit.
14. Decide what a homegrown system will own
The build-versus-integrate question is easier to evaluate as a list of responsibilities than as a comparison of happy-path demos. A homegrown layer needs an owner for each of these decisions:
- Organization identity and the relationship to application customer records.
- Stable capability semantics independent of commercial packaging.
- License validity, revocation, and historical editability.
- Seat uniqueness, capacity invariants, release, and reassignment history.
- Provisioning credentials, expiration, recipient handoffs, and replay behavior.
- Grant provenance and reconciliation of current authorization.
- Account-wide usage definitions and billing-capacity enforcement.
- Idempotent writes and recovery after an ambiguous response.
- Customer-administrator authority without integration-wide privileges.
- Audit provenance, durable event delivery, and operational diagnostics.
These responsibilities do not all demand a separate service or elaborate abstraction. They do demand deliberate answers once the product depends on them. A small model can be the correct model if its limitations match the actual agreements being sold.
Building can be reasonable when licensing is genuinely trivial or a strategically central part of the product. Dedicated infrastructure becomes more attractive as lifecycle, provisioning, capacity, delegation, and operational requirements accumulate. Evaluate the model against real scenarios, not invented delivery-time estimates.
15. Review the architecture with concrete scenarios
Before choosing an implementation, walk through a small set of scenarios with the people responsible for product, backend operations, and customer support.
- A company buys capacity today for access starting next month. Which record owns the start date, and what does an access check return today?
- One employee receives two licenses containing analytics. What happens when one allocation is released?
- An agreement expires while seats remain allocated. Which member, usage, and access views change?
- A seat-creation response is lost. Which request data and retry key does the application retain?
- A customer administrator distributes an invitation. Who authenticates the recipient, and when is capacity checked?
- An event receiver is unavailable. Where can operators inspect delivery attempts, and how does the receiver recover without duplicate business effects?
- A released user is later reassigned. Can delayed recovery tooling accidentally release the replacement allocation?
Answers should identify the authoritative record, the caller's authority, the transactional change, and the recovery path. If the answer is a script that edits several unrelated flags, that is a useful signal about where the model needs clarification. It is not a reason to add more flags.
16. How Business Mode maps onto the architecture
Business Mode provides an organization-access layer alongside an existing application. A Project scopes the integration. An Organization represents a customer company. Entitlements name capabilities. A License combines the organization's distributable capabilities, capacity, and validity. Assignments allocate its seats to stable external user IDs.
Grants preserve the provenance behind those capabilities, and Effective Entitlements provide the authorization projection. Your backend keeps its machine credential server-side and uses hasAccess for the current decision. Your application continues to own user identity, sessions, profiles, and feature enforcement.
The surrounding operational surfaces follow the same model: supported provisioning paths, Organization-admin delegation, assignment history, capacity enforcement, marked idempotent mutations, Audit Log, and Webhook delivery diagnostics. They do not turn Business Mode into an authentication provider or payment processor.
For a capability-focused evaluation, explore Licensing. For the implementation sequence, start with the raw-HTTP Quickstart. Use the detailed concepts and guides to test the model against your own agreements before deciding where the licensing responsibility should live.