---
title: "Licenses"
description: "Show a customer the license keys of the software they hold, the devices each runs on, and give them a new key when theirs leaks."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Licenses

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](#signing-keys) needs a token ([Authentication](/customer-api/authentication)); the examples use the client from [Your own front end](/customer-api/self-hosted#a-minimal-client).

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`](/customer-api/reference/list-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.

```bash
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/slug:pasta-timer/licenses' \
  --header 'Authorization: Bearer ctk_...'
```

```json title="listLicenses 200"
{
  "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
}
```

- `key` is 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 is `null` to staff acting as the customer.
- `status` says 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_by` names the license that holds it.
- `expires_at` is when the access ends, or ended; `null` for lifetime access.
- `activation_limit` is how many devices the key activates at once: the store's own limit for this license, else its tier's, else the product's; `null` means no limit. `activations` are the devices it counts now (`count`) beside that `limit`.

[`GET /v1/stores/{store}/products/{product}/licenses/{license}`](/customer-api/reference/get-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`](/customer-api/reference/rotate-license) 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.

```bash
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`](/customer-api/reference/list-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.

```json title="listLicenseActivations 200"
{
  "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
}
```

- `name` is what the store's software calls the device, such as its name; `null` when it gave none.
- `status` is `active` while the device counts, `inactive` when the store retires devices unseen for a while and this one went unseen that long, and `deactivated` once freed, `deactivated_by` saying by whom (`customer`, `merchant` or `software`).
- 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`](/customer-api/reference/deactivate-license-activation) 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.

```bash
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](/merchant-app/settings#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](/merchant-api/guides/verify-licenses-offline)) against the store's public keys. [`GET /v1/stores/{store}/license_signing_keys`](/customer-api/reference/list-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:

```bash
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/license_signing_keys' \
  --header 'Publishable-Key: <publishable key>'
```

```json title="listLicenseSigningKeys 200"
{
  "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.

Source: https://docs.sherpo.io/customer-api/licenses/index.mdx
