Skip to main content
The self-service portal lets your customers handle routine license tasks themselves; without opening a support ticket. Buyers go to portal.authforge.cc, enter their license key and email, receive a magic code, and land on a page where they can see license status and reset their HWID subject to policy you define.

Why it exists

HWID resets are the single most common support request for license-gated software. The portal gives customers a policy-controlled way to do it themselves:
  • Fewer tickets: users reset their own devices when their policy allows it.
  • Auditable: every reset is logged on the license with timestamp and source.
  • Safe by default: limits and cooldowns are enforced server-side, not suggested.
  • Branded: accent color and display name are published by your app.

How sign-in works

A few deliberate properties of this flow:
  • Constant-time response. The portal always returns the same “if the license and email match, a code was sent” message, whether or not the license exists. This prevents the portal from being used to probe for valid keys.
  • Short-lived challenges. Challenges are stored in DynamoDB with a TTL and are single-use.
  • Stateless sessions. Session tokens are HMAC-signed with a secret in AWS Secrets Manager. No session table to scale.

Email requirement

The portal authenticates on license key + email. A license without an email attached is invisible to the portal, by design.
  • Commerce-created licenses: the buyer’s email is attached automatically by the Commerce pipeline. No action required.
  • Manually-created licenses: you must attach an email before the portal will recognize it.

Attaching an email (dashboard)

  1. Open the app’s Licenses tab.
  2. Click the row menu on the license → Portal Email.
  3. Enter the customer’s email (or clear it). Save.
Licenses with an email attached show a small mail icon next to the key, so you can spot portal-ready rows at a glance.

Attaching an email (Developer API)

Pass "email": null or "" to clear it. Requires the write:licenses scope. You can also pass an email field when creating licenses via POST /v1/licenses; see the Licenses API.

Policy

Each app has a portal policy controlling what end users can do. Configure it in the dashboard under Settings → Portal. When a user attempts a reset, the policy engine (evaluateResetPolicy) walks the license’s reset history and enforces limits before the reset is allowed. Every reset is then recorded via recordPortalReset, so the next attempt sees an up-to-date history.

Branding

Branding is applied dynamically. When a user signs into the portal, the portal fetches the policy for their license’s app and:
  • Swaps the MUI theme to use your accent color.
  • Replaces the header title with your display name.
The login screen itself is generic; branding appears once the user proves ownership of the license. This avoids leaking which app a license belongs to before authentication.

Hosting

The portal is hosted by AuthForge:
  • UI: https://portal.authforge.cc (static Vite app, served via AWS Amplify).
  • API: https://portal-api.authforge.cc (HttpApi behind a Lambda, deployed by our PortalStack).
You do not need to buy a domain or stand up any infrastructure. The portal works for every AuthForge app as soon as policy is published and licenses have emails attached.

What the user sees

After signing in, the user lands on their license home page with:
  • The license key (truncated), status, expiration, and attached email.
  • Bound HWIDs and how many slots remain.
  • A Reset HWIDs button, gated by policy. When the user is over their limit or inside a cooldown, the button is disabled with a clear explanation and (optionally) a link to your support URL.

HWID resets and offline machines

If your app uses self-serve offline activation, a license can activate at most maxHwidSlots distinct machines, ever. HWID resets do not free offline machines. A reset clears the seat bindings, but each machine that activated keeps its lifetime file, so it keeps counting against the cap. Resetting repeatedly gives the buyer no extra activations. Once a license has activated a machine, the portal API returns its offlineMachineCount, so the portal can show how many offline machines are used and that resets do not free them. A buyer who runs out has to contact you; you can release a machine from the dashboard license page or the Developer API. A refund or chargeback revokes the license online but cannot reach files already issued. For a lifetime file, that means the buyer keeps the app.

Should the portal be on?

It depends on how your app signs in:

Why resets do nothing for offline-only apps

When the app never calls login(), a seat is only bound when a machine activates. Every bound seat therefore belongs to a machine that already holds a lifetime file, and the seat count can never be higher than the machine count:
  • Under the cap: a new machine already has a free seat. It does not need a reset.
  • At the cap: a new machine gets offline_activation_limit_reached whether or not the buyer resets.
  • Machines that already activated: keep running from their files. Resets do not touch them.
A buyer who resets just uses up their reset allowance and then hits the same error. Only you can free a machine slot (see above).

Turning the portal off

  • The purchase email no longer links to the portal. It still carries the license key and your support contact. Set the product name and support email under Commerce email delivery on the same settings page.
  • Buyers cannot sign in at portal.authforge.cc for this app.
  • Nothing changes for activation: activate_offline and login_from_file do not use the portal.
The portal is not a way to recover a lost key either, because signing in requires the key.

Keeping a read-only portal

If you want buyers to see their license status and how many offline machines they have used (“Offline machines: 3 of 5 used”), leave the portal on and set the HWID reset limit to 0. The page still loads and shows the license, and customers are asked to contact support instead of resetting. The dashboard shows a warning on Settings → Self-service portal while the portal and self-serve activation are both on.
  • Commerce: Commerce-created licenses are portal-ready automatically.
  • HWID locking: Portal resets clear the bindings the SDK maintains.
  • Licenses API: Attach or change emails programmatically.

Security notes

  • Portal session tokens are HMAC-SHA256 signed; the secret lives in AWS Secrets Manager (PortalSessionSecret).
  • Magic codes are 6 digits, single-use, and expire inside a short TTL.
  • Every user action (login, verify, reset) is logged with a request ID for support traceability.
  • The email lookup is case-normalized and trimmed; the comparison itself is constant-time.