Scoped tokens

A scoped token gives access to the resources of one customer, for a limited time, and only for what its permissions allow. Unlike an API key, which can do anything in your organization, a scoped token is safe to put in your customers’ hands: your backend creates it, and sends it to a page of your website or to your app, which then calls LicenseManager directly.

For Acme Studio, it’s how the My licenses page of their own website works. When a signed-in photographer opens it, Acme’s backend creates a customer token for them and passes it to the page. The page then lists the photographer’s licenses and deactivates their old laptop by calling LicenseManager itself: Acme’s backend doesn’t relay every request, and the API key never leaves it.

Token types

A token is scoped to a customer, a license or a machine, and reaches:

• The resource it’s scoped to.
• The resources above it: a license token reaches its customer.
• The resources below it: a license token reaches its machines.

But not the resources beside it: a license token doesn’t reach the customer’s other licenses.

A resource the token doesn’t reach answers 404, as if it didn’t exist.

Permissions

Each token holds a list of permissions, its scope. A write permission includes the matching read one.

Give each token only what the page needs: a page listing licenses needs license:read, not machine:write.

Create a token

From your backend, with an API key:

curl -X POST https://api.licensemanager.dev/v1/customers/c9Wd3RtE/tokens \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": ["customer:read", "license:read", "machine:write"],
    "expiresInSeconds": 3600
  }'

// 201 Created
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "type": "customer",
  "scope": ["customer:read", "license:read", "machine:write"],
  "expiresAt": "2026-10-14T11:30:00.000Z"
}

Requests made with a session of the app can create tokens too, when the member’s role allows it: owners, admins and members, not viewers.

Tokens creating tokens

A token can create tokens for the resources below it, so the page holding it can hand a narrower token on, without going back to your backend:

A token can’t give more than it has:

• Permissions: only the ones it holds. A customer token with license:read and machine:write can create a machine token with machine:read, not one with customer:read. Asking for more answers 403 with insufficient_scope.
• Expiration: no later than its own. A longer expiresInSeconds is shortened to the creating token’s expiration: check the expiresAt of the response.

For Acme Studio, a team admin’s account page holds a customer token. When the admin opens one of the team’s licenses, the page creates a license token with license:read and machine:write, and passes it to the seat manager widget, which can’t see the team’s other licenses.

Use it in your pages

import { Configuration, LicensesApi } from "@licenseman/sdk";
 
const licensesApi = new LicensesApi(new Configuration({ accessToken: token }));
const { data: licenses } = await licensesApi.listCustomerLicenses({ customerId });

Endpoints accepting tokens

Only these endpoints accept tokens. Every other one answers 403 with token_not_allowed.

Errors

Revoking a token

To cut access right away in an emergency, like a token leaked in a log, you can delete the customer, which first requires deleting their licenses: usually, waiting for the token to expire is the better option.

Security

• Tokens are signed, so they can’t be changed or forged, but their content can be read by whoever holds them: the resource’s id, the permissions and the expiration.
• Anyone holding a token can use it: send it over HTTPS only, and keep it out of URLs your servers log. The customer portal removes the token of a portal link from the address bar for that reason.
• Create tokens for the signed-in customer only. Your backend decides who gets a token: check the customer you create it for is the person signed in to your website.

Edge cases

Test products. Tokens of test products reach test resources, whatever key created them: the live or test mode only limits API keys. A test API key creates tokens of test resources only.

Usage. Requests made with a token, creating a token included, count toward your plan’s API requests, like requests made with an API key, but aren’t rate limited. See rate limits and quotas.

Who did it. What a token does is recorded on the events as Customer token, License token or Machine token.

Machine tokens and validation. A machine token doesn’t replace validating the key: the license token returned by a validation is what your app checks offline. A machine token only lets it call the endpoints above for its machine.