License each tenant
This page is for whoever builds licensing into an app that serves businesses, each with its own users. If your software has its own accounts and tenants, license each tenant rather than each user. A tenant buys seats: the license issues one seat for each, under one subscription. Your backend issues one credential per seat, keeps it against the tenant, and runs each request under one of the tenant’s seats. Your users never become Monaiq accounts and never hold a license code.
Every seat shares the license’s features, but each seat carries its own rate windows and its own allowance; nothing is pooled across a license’s seats.
Monaiq bills for the seats and issues them. Which person or request runs under which seat is your application’s rule, made in your backend. The SDK never chooses a seat.
The flow
Section titled “The flow”- Create a checkout for the tenant. From your backend, create an
embedded checkout. Set
CorrelationIdto your own tenant id,Quantityto the seats bought, andSuccessUrl,CancelUrlandReturnUrlto routes on your site (a paid offering needs the first two, a free one the last). Send a differentRequestIdfor every purchase: a repeatedRequestIdis the same purchase, and the sameRequestIdwith a differentQuantityis refused. Save theCheckoutIdyou get back on your server under thatRequestId. - Send the buyer on, now. A paid offering returns a payment URL; a free offering returns a
claim link. Redirect the buyer to whichever you got, in the same browser. After paying they are
sent to
SuccessUrl?request_id=.... On the claim link they confirm the license, prove the address with a one-time code, and are sent back toReturnUrl?request_id=.... The claim link is also emailed, as a fallback for a buyer who closed the tab, never as the path. - Read the result. When the buyer lands on your page, look up the
CheckoutIdyou saved under itsrequest_idand read the result with it. A claim is already completed; a payment may still be settling, so read again while it readspending. Poll only if you set noReturnUrl. The result names the license (LicenseId) and its seats (SeatIds). A purchase of one seat also carries that seat’s license code (EncodedCredential); for more than one seat there is none: issue one per seat yourself. - Find the tenant’s license.
GET /licensing-mgmt/licenses?correlationId=<tenant id>finds it by your own id, andGET /licensing-mgmt/licenses/{licenseId}/seatslists its seats. Every seat of one license carries the sameLicenseId. - Issue one credential per seat. Issue a license code for every live seat, with a label that names the seat in your own terms, and keep it in your secret store against the seat. It is shown once. Treat it as a secret: it authorizes and meters that seat.
- Run each request under a seat. In .NET, register your own
ILicensingContextProviderwithAddSidubLicensing<TContextProvider>(). It resolves the licensing context once per request scope, so it returns the credential of the seat your application assigns to the request. Assigning seats covers the assignment.
Assigning seats
Section titled “Assigning seats”Which seat a person or a request runs under is your application’s decision. A seat’s rate windows and allowance are that seat’s alone, so the assignment decides whose uses count against which allowance.
The plain case is a seat for each user. A seat belongs to a named person, your application records which seat is whose, and that person’s work always runs under it. The provider returns the credential of the current user’s seat:
using Sidub.Licensing.Context;
public sealed class UserSeatContextProvider( ICurrentUser user, // yours: the user of the current request ISeatStore seats) // yours: which seat is whose, and its stored credential : ILicensingContextProvider{ public async Task<LicensingContext?> ResolveContextAsync(CancellationToken cancellationToken = default) { var seat = await seats.FindForUserAsync(user.Id, cancellationToken);
// null: this user has no seat, so there is no license to run under return seat is null ? null : LicensingContext.FromEncodedString(seat.EncodedCredential); }}Register it: builder.Services.AddSidubLicensing<UserSeatContextProvider>();.
Nothing moves that person’s use to another seat. When their seat’s allowance is spent, their use
throws AllowanceExhaustedException with the reset date, whatever the tenant’s other seats have
left.
Your application may assign seats by another rule: a seat for each team or machine, or a pool the
tenant’s requests share. That is your application’s policy, built in your own code; the SDK has
no helper for it. Each seat’s state is readable for it:
ILicenseStateProvider.GetState(serviceReference, context) in .NET and client.getState() in
Node return the seat’s allowance figures, read from the platform when the runtime holds none or
old ones; the read uses none of the allowance. A seat no instance of your application has served
this period reads the same as a busy one. A seat’s figures are unknown only while its
PeriodEndUtc is null, and a seat with nothing left reads Remaining 0 with its reset date.
Showing what is left lists each figure.
To report every seat of a tenant’s license in one call, with no runtime per seat, read
GET /licensing-mgmt/licenses/{licenseId}/seats from your
backend: each live seat carries its figures under Allowances.
Every seat of a license resets together, at the PeriodEndUtc its seats report. A seat whose
rate window is full is refused until the window has room again: its assertion throws
RateLimitException.
Associating a purchase made elsewhere
Section titled “Associating a purchase made elsewhere”A license code is how a purchase made anywhere reaches the application it was bought for, and every integrating application accepts one. A tenant that bought on your storefront or in the Monaiq portal holds a code from the checkout, or issues one on any seat of the license. Let an owner of the tenant paste it into your application, then:
- Fetch an authorization with the pasted code. A refusal means the code is revoked, retired or not a license code at all.
- The authorization names the license (
LicenseId) and the seat. Read the license,GET /licensing-mgmt/licenses/{licenseId}: a404means it was issued by somebody else. The row carries the license’sStatusand its features. - Check the license is not already linked to another tenant. A license code proves the purchase,
not who is pasting it, and any code of the license names the same
LicenseId. Record which tenant linked each license, and refuse a code whose license another tenant already holds, unless your application shares purchases between tenants on purpose. - List every seat of the license:
GET /licensing-mgmt/licenses/{licenseId}/seats. - Issue one credential per live seat, labelled, and store each against the tenant.
- Discard the pasted code. The seats now run on license codes you issued and can revoke. The pasted code stays the buyer’s: it authorizes and meters one seat they paid for.
Upgrading, and more seats
Section titled “Upgrading, and more seats”A tenant holds one plan of a product at a time. The rules (one plan of a product, one license of
an offering, free and trial once) apply per CorrelationId when you give one: a tenant that
already holds a plan of the product is refused a second plan, and a second purchase of the same
offering is refused, for that tenant. A different tenant of the same buyer is separate.
To move a tenant to another plan, the buyer changes plan from their Monaiq license page. Your app
sees the new OfferingId on the same license and the same seats, so nothing is re-keyed: your
users, connections and machines keep working. To move a tenant from a trial or a free plan to a
paid one, create a paid checkout with the same CorrelationId; the paid license replaces the trial
when it starts. On return, associate the new purchase as in the flow, then revoke the
license codes of the seats the new purchase replaces.
To give a tenant more seats, the buyer adds them to the license they have, from their license page (on a one-time purchase they pay for the added seats once), or your server adds them through the seats call on a subscription. Sync on the signals below.
Record the address that paid. That person manages the subscription, its invoices and its payment method in the Monaiq portal.
Keeping the seats in step
Section titled “Keeping the seats in step”Seats change in the Monaiq portal as well as through your backend. Sync a license on these signals; nothing runs on a timer:
- A code is pasted. Associating the purchase is the sync.
- You changed something. After you add or retire a seat, sync once.
- A seat is refused.
GetAuthorizationthrowsLicenseAuthorizationDeniedExceptionwith the reason:SeatRetired,LicenseSuspended,LicenseCancelledorExpired. A code the buyer revoked is refused withLicensingApiExceptioncodeCredentialRevoked.GetStatereturns null for either and logs why. Sync that seat’s license once and show the tenant what you found. - The tenant asks. Put a sync control next to the paste box. Seats added in the portal reach you this way.
A sync is:
- List the license’s seats by
LicenseId. - Issue a license code for every live seat that has none.
- Drop a seat whose
RetiredUtcis set. Its license codes are already revoked. - Read the license’s
Status.SuspendedandCancelledrefuse every seat of the license at its next authorization; show the tenant its billing state and the Monaiq portal link.
From your backend, add seats to a license: the customer’s card is charged now for the new seats for the rest of the period, and they come back in the response, each with no license code yet. Retire a seat the tenant no longer needs: it leaves the price at the next period, its license codes are revoked, and it is refused at its next authorization.
A change reaches a running seat at its next authorization refresh. The refresh interval is the authorization duration in Credentials and keys.
Machines and self-hosted deployments
Section titled “Machines and self-hosted deployments”A machine, a build agent or a deployment the tenant runs itself holds a credential of one seat. Issue it from your backend after the operator signs in to your application, label it with the machine’s name, and revoke it to cut the machine off. A deployment the tenant runs holds the credential in its own configuration and needs no key of yours.
After the sale
Section titled “After the sale”The management API is for your backend:
- Find a tenant’s license by your own id with
GET /licensing-mgmt/licenses?correlationId=..., without storing Monaiq’s ids. The license carries its status and term; each seat carriesLicenseStatusandRetiredUtc. - Add seats to a license. The customer’s card is charged now for the new seats for the rest of the period.
- Retire a seat the tenant no longer needs. It leaves the price at the next period, its license codes are revoked, and it is refused at its next authorization. On a one-time license you can send a refund choice and a reason with the call, and the seat’s price goes back to the card that paid; the customer is emailed the reason.
- Issue or revoke a license code for a seat you issued.
None of these operations is an MCP tool: licenses, seats and license codes are management API and portal work.
Things to know
Section titled “Things to know”- The claim needs the right address. A free checkout is claimed by the buyer signing in. The
account they sign in with must be the one for the address you sent as
CustomerEmail, so send the address they will actually use. - The buyer sees your name. The buyer sees your business name, or your legal name if you have not set one; with neither they see “a seller on Monaiq”. Set it in Settings before you send anybody a claim.
- The last seat cannot be retired. A license always keeps at least one live seat. To end the license, cancel it instead. A cancelled license stops working, bought outright or not.
- A retired seat stays retired. It is listed with its
RetiredUtc, keeps no license codes, and cannot be added back. Add a seat instead. - Seats change only on an active license. A paused, suspended or cancelled one refuses the change, and a one-time purchase takes added seats only from the buyer, on their license page, because your server cannot pay for them.
- Monaiq’s own plans are one seat. They are refused in multiples.