Add managed user product line with account-bound licensing and optional activation cards

[banbanzhige]

Problem

Hi, first of all, thank you for building and maintaining Keygate.

The current Desktop / SaaS / Hybrid product models already cover many common licensing scenarios well. While working on my own use case, I found another product pattern that may also be useful for Keygate users.

Some products need Keygate to act as a transparent backend rather than a user-facing customer portal. In these cases, the business application owns the user experience, while Keygate handles accounts, licenses, entitlement history, device activation, and admin operations behind the scenes.

Example scenarios include:

• desktop or client applications with their own login UI
• products where purchase should immediately activate entitlement for an account
• reseller or third-party activation/recharge cards
• subscription products where renewals add time to an account
• apps that want Keygate as the license backend without exposing the Keygate Portal to end users

For these cases, license keys alone are not always the best user experience. The product often needs account-bound licensing, managed user credentials, email verification, password reset, and optional activation card redemption.

Proposed solution

I would like to propose a new product type: managed_user.

It would sit alongside the existing product types: desktop / saas / hybrid / managed_user.

The main idea is that managed_user products have product-scoped managed accounts inside Keygate. The end user does not enter the normal Keygate Portal; instead, the business application calls Keygate APIs directly.

The proposed feature set includes:

Product and plan support

• New product type: managed_user
• Product-level options:
  • enable/disable managed self-registration
  • require email verification
  • enable/disable activation cards
  • card delivery mode
• Managed-user plan license types:
  • subscription
  • perpetual
  • trial
  • account_bound
  • activation_card
• Duration fields:
  • duration value
  • duration unit
  • starts on first use

Managed user account system

• Product-scoped account registration
• Product-scoped email uniqueness
• Product-scoped password hash
• Email verification
• Password reset
• Email change flow
• Login/logout
• Current managed user API
• Admin create/disable/anonymize managed user

Account-bound license grants

• Admin grant license to an existing managed user
• API grant by managed user ID, external customer ID, account, or email
• Idempotent external order handling
• License duration snapshot from plan
• Managed entitlement ledger
• Multiple licenses can stack duration
• Aggregate entitlement calculation
• First-device-activation timing support

Device activation

• Managed-user device activation
• Verify active device entitlement
• Deactivate device
• Activation limit support
• First activation starts the license timer when enabled
• License lifecycle events for grant, first use, activation, revoke, and refund

Activation cards

Optional activation card support for managed_user products:

• Create card batches
• Export card batches
• Sell card through API
• Redeem card as managed user
• Card expiration before redemption
• Card revoke
• Card status tracking: available, sold, redeemed, revoked, expired
• Optional recoverable encrypted card code storage
• Card redemption creates an account-bound license and ledger entry
• Card duration stacks with existing entitlement

Purchase / Stripe flow

• Managed-user checkout flow
• License grant on successful purchase
• Subscription renewal adds new entitlement duration
• Full refund revokes/refunds the managed license and ledger entry
• Activation-card plans use inventory/sale/redemption instead of direct checkout license creation

Admin UI

• Product form support for managed_user
• Plan form support for managed license types and duration fields
• Managed user admin page
• Managed user detail, licenses, events, and aggregate entitlement
• Admin grant flow
• Password reset, disable, anonymize actions
• Activation card batch, inventory, export, sell, and revoke flows

Portal isolation

• Managed-user products do not appear in the normal customer portal
• Managed-user licenses do not appear in normal portal license management
• Managed-user device management is handled through managed APIs instead

Webhooks and audit

• Audit logs for managed user and license actions
• Webhook events such as:
  • license.created
  • license.revoked
  • activation_card.batch_created
  • managed_user.created
  • managed_user.disabled
  • managed_user.anonymized

I have a working local implementation for most of this and I am currently testing it end to end before preparing a PR.

Before opening a PR, I wanted to ask whether this direction fits the project’s roadmap and architecture. If you are open to it, I can prepare the PR in smaller reviewable parts, such as:

1. Data model and product/plan validation
2. Managed user auth APIs
3. Managed license grant and entitlement ledger
4. Device activation flow
5. Activation card support
6. Admin UI
7. Stripe / webhook integration
8. Documentation and OpenAPI updates

I am happy to adjust naming, API shape, or split the implementation differently if you prefer another direction.

Alternatives considered

No response

[alanisme]

Thanks, real work and the use case is valid. Some of this overlaps with what's already on the roadmap, so I'd rather
coordinate than have a big PR land before the shape is settled.

The piece I'd push back on is making managed_user a new product type. It adds a parallel system inside Keygate
(second user, license, device, admin surface) and the maintenance cost compounds forever.

Pieces that fit cleanly and are likely to land anyway: activation cards as a standalone module, a
renewal_extends_duration plan flag, a "start timer on first activate" flag.

Less likely in core: managed_user as a discriminator, password/verification auth (OTP-only is intentional), the
parallel ledger.

If you want to contribute, the cleanest first slice is activation cards as a small migration + model + admin list
PR. Lock the data model first.

[banbanzhige]

Thanks again. I think your concern about a large parallel system is fair, and I don’t want to push the whole framework as a big PR before the shape is agreed.

The part I’d like to discuss first is the domain model separation.

In my use case, a customer is not always the end user. A customer can be a buyer, company, reseller, distributor, or admin/operator. The actual end user may only be a product-scoped account inside the business application, with no need to access the Keygate portal or understand the underlying licensing system.

I see a similar separation between licenses and activation cards:

• A license is the actual entitlement/permission record.
• An activation card is an inventory/redemption instrument.
• Direct official sales can create licenses directly.
• Reseller or third-party sales can sell cards first, then redeem them into licenses/entitlements later.

So the model I’m trying to validate is:

• Customer / buyer / reseller
• Product-scoped account
• License / entitlement
• Activation card as a distribution and redemption channel

I understand that the full account-based product line may still be too large for core. But I think these concepts may be useful even if they land as smaller primitives first: activation cards, first-use timing, duration stacking, and account-bound entitlements.

I have a working fork/demo that implements this separation in the admin UI and backend. I can share it as a reference implementation only, not as a merge request, if that would help the design discussion.

A related direction is delegated customer management. In the longer term, I think some customers should be able to log into the Keygate portal with scoped permissions. A merchant, company admin, or reseller may need to manage product-scoped accounts under their own customer relationship: check account status, inspect active devices, issue compensating entitlement time, or revoke/suspend an entitlement for refunds, abuse, or support intervention.

That role is not the same as a global Keygate admin, and it is not the same as an end user. It would be a scoped customer/operator role that can manage its own users and entitlements, but not system settings, global products, API keys, billing provider configuration, or other customers’ data.

If you are open to looking at it, I can share the fork with a short walkthrough instead of asking you to review the entire branch. The walkthrough would point to:

1. Products: account-based product mode
2. Customers: customer vs product-scoped accounts
3. Licenses: licenses vs activation-card inventory
4. Plans: activation-card plans, first-use timing, duration, and device limits
5. API/schema boundaries for the above

I also added docs/QB_CHANGELOG_EN.md as an implementation map for the fork. It documents the main backend, admin UI, OpenAPI, migration, Stripe, activation-card, and portal-isolation changes. It is there for orientation, not as a request to review every line.

QB_CHANGELOG_EN.md

[banbanzhige]

PS：I created a public mirror here, since I can’t make my main fork public directly:

https://github.com/banbanzhige/keygate-reference

It’s only a reference implementation for the discussion above, not a merge request.

[banbanzhige]

PS：I created a public mirror here, since I can’t make my main fork public directly:

https://github.com/banbanzhige/keygate-reference

It’s only a reference implementation for the discussion above, not a merge request.

By the way, I haven't iterated the old version of the customer and user system yet. The current version is running as expected, and I have already completed the activation card