Every customer who holds a software product has one license for it, with a key they enter in the app. The key is issued with their first purchase, subscription or grant, keeps working while their access lasts, and stays the same across renewals and plan changes. Everything here but the store’s signing keys needs a token (Authentication); the examples use the client from Your own front end.
On your Sherpo storefront this is already built in: the customer’s library and the product’s page show the key with the devices it activates, a way to free one and a new key once the customer confirms; the order page shows the key too, and Sherpo emails it in the access granted and subscription started emails, under the product. The rest of this page is for your own front end. Your app checks keys from your server through the merchant API, never with a customer’s token.
List a customer’s licenses
GET /v1/stores/{store}/products/{product}/licenses pages the customer’s licenses of a software product, with read, newest first: the live one, and the ones it replaced. Licenses made in the same second sort by id. It answers not_found when no product has that id or slug.
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/slug:pasta-timer/licenses' \
--header 'Authorization: Bearer ctk_...'{
"items": [
{
"id": "<license id>",
"product_id": "<product id>",
"key": "PASTA-7Q4XM-R2KD9-HB6TN-W3FZC-K2P9D",
"status": "active",
"expires_at": null,
"activation_limit": 5,
"activations": { "count": 2, "limit": 5 },
"replaced_by": null,
"created_at": "2026-11-10T14:30:00.000Z"
}
],
"cursor": null
}keyis what the customer enters in your app. Show it to them alone, as you would a password. It comes over MCP too, so an assistant can tell the customer their key. It isnullto staff acting as the customer.statussays whether the key works:active: the customer holds the product.expired: their subscription or their access ran out.revoked: a refund, a lost dispute or the store took their access back.disabled: the store turned the license off.replaced: the customer got a new key;replaced_bynames the license that holds it.
expires_atis when the access ends, or ended;nullfor lifetime access.activation_limitis how many devices the key activates at once: the store’s own limit for this license, else its tier’s, else the product’s;nullmeans no limit.activationsare the devices it counts now (count) beside thatlimit.
GET /v1/stores/{store}/products/{product}/licenses/{license} reads one, with read. A license of another customer, or one under another product, answers not_found.
Get a new key
POST /v1/stores/{store}/products/{product}/licenses/{license}/rotate replaces an active license with a new key, with profile:write. The old key stops working at once and its license reads replaced, so the app that held it has to be given the new key. The answer is the new license, and Sherpo emails its key to the customer a couple of minutes later, unless the key is replaced again before the email goes. A license gets at most five key emails in any 24 hours, the store’s own rotations included: past that, the new key still works and shows in the library, but no email is sent. The old key’s devices are freed with it, and the new license starts with none, so each device activates again with the new key. The new license keeps the store’s own activation limit, its metadata and its use count, as a rotation through the merchant API does, so replacing a key never resets a limit the store sets on uses. It answers conflict on status with the license’s status (expired, revoked, disabled or replaced) when the key no longer works, as there’s nothing to replace. A key may be replaced again a minute after it was made, and a customer may replace one license three times in any 24 hours (the store’s rotations don’t count): past either, it answers not_permitted with reason: "limit" and retry_at, which the REST API sends as Retry-After, so a loop can’t fill the customer’s inbox.
curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/slug:pasta-timer/licenses/<license id>/rotate' \
--header 'Authorization: Bearer ctk_...'Getting a new key is a REST operation alone, never an MCP tool: it stops the key the customer’s app holds, so only your own front end offers it, after the customer confirms.
Free a device
The store’s software activates the key on each device it runs on, up to the license’s limit. A customer who replaced a computer frees the old one so the new one can take its place.
GET /v1/stores/{store}/products/{product}/licenses/{license}/activations pages a license’s devices, with read, latest activated first, freed and inactive ones too. Filter on status to show only the ones that count.
{
"items": [
{
"id": "<activation id>",
"license_id": "<license id>",
"name": "Studio Mac",
"status": "active",
"created_at": "2026-11-10T14:35:00.000Z",
"activated_at": "2026-11-10T14:35:00.000Z",
"last_seen_at": "2026-11-14T08:02:00.000Z",
"deactivated_at": null,
"deactivated_by": null
}
],
"cursor": null
}nameis what the store’s software calls the device, such as its name;nullwhen it gave none.statusisactivewhile the device counts,inactivewhen the store retires devices unseen for a while and this one went unseen that long, anddeactivatedonce freed,deactivated_bysaying by whom (customer,merchantorsoftware).- A device’s own id never leaves the software that sent it, so it’s never answered.
POST /v1/stores/{store}/products/{product}/licenses/{license}/activations/{activation}/deactivate frees one, with profile:write, whatever the license’s status. The answer is the freed device with the license’s activations. A device already freed answers not_found, as does a license of another customer.
curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/slug:pasta-timer/licenses/<license id>/activations/<activation id>/deactivate' \
--header 'Authorization: Bearer ctk_...'Freeing a device is a REST operation alone, never an MCP tool: it stops the software on that device, so only your own front end offers it, after the customer confirms. Listing devices is an MCP tool too.
In emails
Sherpo puts the key under each software product in the access granted email, and in the subscription started email of a software subscription, with the devices it activates and a link to the customer’s library. A key that no longer works by the time the email goes is left out. An access granted email shows up to eight keys; when more software unlocks at once, it says the other keys are in the library. These are emails the store can turn off (Customer messages), so show the key in your own front end too. A new key, from the customer’s rotation or the store’s, is emailed on its own, which the store can’t turn off.
Signing keys
When the store’s software runs offline, it checks a signed token the seller’s server hands it (Verify licenses offline) against the store’s public keys. GET /v1/stores/{store}/license_signing_keys answers them as a JSON Web Key Set with the store’s publishable key, or a customer’s token, so software can fetch the set while online and keep it:
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/license_signing_keys' \
--header 'Publishable-Key: <publishable key>'{
"keys": [
{
"kid": "<key id>",
"kty": "OKP",
"crv": "Ed25519",
"x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
"alg": "EdDSA",
"use": "sig",
"status": "current",
"created_at": "2026-08-14T10:00:00.000Z",
"expires_at": null
}
]
}status is current for the key that signs, next for the one that signs after the store rotates its keys, and previous for one rotated out, kept until expires_at so tokens it signed still verify. status, created_at and expires_at are Sherpo’s own members beside the standard JWK ones, which JSON Web Key Set readers skip. The set holds public keys alone; the store has none until its first device activates or the seller creates them.