Skip to content

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.

  1. Create a checkout for the tenant. From your backend, create an embedded checkout. Set CorrelationId to your own tenant id, Quantity to the seats bought, and SuccessUrl, CancelUrl and ReturnUrl to routes on your site (a paid offering needs the first two, a free one the last). Send a different RequestId for every purchase: a repeated RequestId is the same purchase, and the same RequestId with a different Quantity is refused. Save the CheckoutId you get back on your server under that RequestId.
  2. 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 to ReturnUrl?request_id=.... The claim link is also emailed, as a fallback for a buyer who closed the tab, never as the path.
  3. Read the result. When the buyer lands on your page, look up the CheckoutId you saved under its request_id and read the result with it. A claim is already completed; a payment may still be settling, so read again while it reads pending. Poll only if you set no ReturnUrl. 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.
  4. Find the tenant’s license. GET /licensing-mgmt/licenses?correlationId=<tenant id> finds it by your own id, and GET /licensing-mgmt/licenses/{licenseId}/seats lists its seats. Every seat of one license carries the same LicenseId.
  5. 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.
  6. Run each request under a seat. In .NET, register your own ILicensingContextProvider with AddSidubLicensing<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.

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.

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:

  1. Fetch an authorization with the pasted code. A refusal means the code is revoked, retired or not a license code at all.
  2. The authorization names the license (LicenseId) and the seat. Read the license, GET /licensing-mgmt/licenses/{licenseId}: a 404 means it was issued by somebody else. The row carries the license’s Status and its features.
  3. 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.
  4. List every seat of the license: GET /licensing-mgmt/licenses/{licenseId}/seats.
  5. Issue one credential per live seat, labelled, and store each against the tenant.
  6. 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.

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.

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. GetAuthorization throws LicenseAuthorizationDeniedException with the reason: SeatRetired, LicenseSuspended, LicenseCancelled or Expired. A code the buyer revoked is refused with LicensingApiException code CredentialRevoked. GetState returns 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:

  1. List the license’s seats by LicenseId.
  2. Issue a license code for every live seat that has none.
  3. Drop a seat whose RetiredUtc is set. Its license codes are already revoked.
  4. Read the license’s Status. Suspended and Cancelled refuse 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.

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.

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 carries LicenseStatus and RetiredUtc.
  • 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.

  • 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.