> Keygen: what your AI agent should know — from The Handover, the-handover.org/services/keygen
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

# Keygen

What we tell an AI agent working on a project that uses Keygen: 2 rules, 2 learned the hard way.

Build a full rootnote set for a Keygen project: https://the-handover.org/build?areas=working-agreement,licensing&licensing=keygen

The vendor's own file for agents (what Keygen is, where its documentation lives): https://keygen.sh/llms.txt. This page covers where it catches agents out.

### Keep entitlement separate from billing, with one webhook as the only wire between them

> Hard-won · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-19

- **Billing knows who paid. The licence system knows what they may use.** Keep
  them as separate systems, and let one verified webhook be the only connection.
- A payment processor that does not issue licence keys fulfils *after* the
  webhook, which makes the webhook handler the fulfilment step — not an
  afterthought to it. Treat it as production code with its own tests.
- **Do not let licensing logic grow inside the billing integration.** It is the
  part that has to survive changing payment provider, and here the provider did
  change.

### Keygen: a product-scoped token, never the admin one — and confirm the scope by watching it fail

> Hard-won · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-19

- **Give the server a product-scoped token, never the account admin token**, and
  ship neither in the client.
- **Confirm the scope live.** The calls the server needs should succeed and the
  ones you withheld should return 403. A scope you only read about is a scope you
  assumed.
- Reference the token by name from a secret store; never paste it where an agent
  session will echo it.

Also applies to every licensing choice, so not repeated here: Revoke a licence when what was paid for ends, never when the customer cancels; A licence check must never lock out somebody who paid.