Licenses API

Issue, manage, and revoke software licenses. Each license includes a signed JWT token.

GET /api/v1/apps/:slug/licenses

List all licenses with optional filtering.

Query Parameters

Parameter	Type	Description
`status`	string	"active", "expired", or "revoked"
`customer_id`	string	Filter by customer
`tier_id`	string	Filter by tier

POST /api/v1/apps/:slug/licenses

Issue a new license with a signed JWT token.

Request Body

Field	Type	Required	Description
`installation_id`	UUID	Yes	Unique identifier for this installation
`customer_id`	string	Yes	Customer reference
`tier_id`	string	Yes	Tier reference
`features`	string[]	No	Feature slugs to enable
`duration_days`	integer	No*	License duration in days
`expires_at`	datetime	No*	Specific expiration date
`forever`	boolean	No*	Set true for perpetual license

* One of duration_days, expires_at, or forever is required.

Example Response

{
  "data": {
    "id": "lic_abc123",
    "installation_id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "status": "active",
    "tier": "pro",
    "features": ["api_access"],
    "expires_at": "2027-01-23T00:00:00Z",
    "created_at": "2026-01-23T10:00:00Z"
  }
}

GET /api/v1/apps/:slug/licenses/:id

Get a single license by ID. Includes the JWT token.

GET /api/v1/apps/:slug/licenses/by-installation

Look up a license by installation_id.

Example

$ curl "/api/v1/apps/my-app/licenses/by-installation?installation_id=550e8400-..." \
  -H "Authorization: Bearer sk_live_..."

DELETE /api/v1/apps/:slug/licenses/:id

Permanently delete a license.

License Actions

POST /api/v1/apps/:slug/licenses/:id/regenerate

Generate a new JWT token with refreshed features from the current tier configuration. Supports two authentication methods.

Authentication Options

API Key (sk_*)

Use Bearer token in Authorization header. Full admin access.

License Token

Provide current_token in request body. Allows self-renewal.

Request Body (optional)

Field	Type	Description
`current_token`	string	Valid, non-expired license token for self-authentication

Examples

# With API key
$ curl -X POST /api/v1/apps/my-app/licenses/lic_abc123/regenerate \
  -H "Authorization: Bearer sk_live_..."

# With license token (self-renewal)
$ curl -X POST /api/v1/apps/my-app/licenses/lic_abc123/regenerate \
  -H "Content-Type: application/json" \
  -d '{"current_token": "eyJhbGciOiJSUzI1NiIs..."}'

# Response
{
  "data": {
    "id": "lic_abc123",
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "tier": "pro",
    "features": ["api_access", "webhooks", "analytics"]
  }
}

Feature Refresh

Regeneration fetches the latest features from the license's tier configuration. If the tier has been updated with new features, the regenerated token will include them. Per-license custom features are preserved and merged with tier features.

Error Responses

Status	Condition
`400`	License is revoked or expired, tier missing, or invalid token
`401`	No authentication provided (neither API key nor current_token)
`403`	Public API key (pk_) used - requires secret key (sk_)

POST /api/v1/apps/:slug/licenses/:id/revoke

Permanently revoke a license. Cannot be undone.

Response

{
  "data": {
    "id": "lic_abc123",
    "status": "revoked",
    "revoked_at": "2026-01-23T15:00:00Z"
  }
}

POST /api/v1/apps/:slug/licenses/:id/extend

Extend a license's expiration. Generates a new token with updated exp claim.

Request Body

Field	Type	Description
`duration_days`	integer	Days to add to current expiration

Customers API Verification API