Reference

Licenzy API reference

Reference the Licenzy /v1 runtime API and /portal setup API, including checkout, access checks, entitlements, usage consumption, and webhook endpoints.

Start free in test mode. Go live when you're ready.

Category: Reference4 sections

Runtime API: /v1

Use these endpoints from your backend during normal product operation.

The /v1 runtime API is the surface your application backend uses while the product is operating. It covers checkout creation, access checks, entitlement reads, usage consumption, and operational webhook delivery controls.

Use these routes from server-side code with a Licenzy API key. Do not expose that key to the browser.

POST/v1/checkout/session

Create a checkout attempt and receive the Stripe checkout URL.

POST/v1/access/check

Return a boolean access decision for a subject.

GET/v1/customer/access/:subject_ref

Return access status plus entitlement summary for a subject.

GET/v1/entitlements/:subject_ref

Inspect entitlement state directly.

POST/v1/usage/consume

Atomically consume usage-pack units.

POST/v1/webhooks/stripe/tenant

Inbound Stripe webhook endpoint called by Stripe, not by your app.

POST/v1/webhooks/stripe/billing

Inbound Stripe billing webhook endpoint called by Stripe, not by your app.

PUT/v1/webhooks/endpoint

Configure outbound webhook delivery.

GET/v1/webhooks/outbound

Inspect outbound webhook deliveries.

POST/v1/webhooks/outbound/:id/requeue

Requeue one outbound delivery.

POST/v1/webhooks/outbound/:id/resend

Resend one outbound delivery.

POST/v1/webhooks/outbound/requeue-dead

Requeue dead outbound webhook deliveries.

  • Use runtime endpoints from your backend during checkout, access and usage flows.
  • Stripe webhook routes are operational endpoints for Stripe to call, not routes your app should call directly.

Portal API: /portal (dashboard and internal setup)

Use these routes only for dashboard setup, workspace configuration, and operator workflows, not for product runtime integrations.

The /portal API is for workspace setup and dashboard operations. It manages the configuration that runtime calls depend on, including Stripe connection details, API keys, and product mappings.

Your product integration should not call portal routes when a customer buys, checks access, or consumes usage. Configure through the portal surface first, then use /v1 from your backend at runtime.

GET/portal/me

Return workspace, account and session context.

GET/portal/account/subscription

Return plan, access state and account subscription details.

GET/portal/stripe/connection

Read stored Stripe connection status for test and live modes.

PUT/portal/stripe/connection

Save Stripe credentials and webhook secret for a mode.

GET/portal/api-keys

List API keys for the current workspace.

POST/portal/api-keys

Create a new API key.

POST/portal/api-keys/:id/revoke

Revoke an existing API key.

GET/portal/products?mode=test|live

List products for the selected mode.

POST/portal/products

Create a product mapping.

PUT/portal/products/:product_code

Replace or restore a product by product code.

PATCH/portal/products/:id

Partially update a product by ID.

DELETE/portal/products/:id

Delete a product by ID.

  • Use portal routes for setup and operator workflows, not for backend runtime execution.
  • /portal/stripe/connection, /portal/api-keys and /portal/products configure the system your runtime API depends on.
Separation rule
Do not use portal routes as part of checkout, access or usage execution. Portal routes configure the system for internal workspace and dashboard operations; runtime routes under /v1 are the product-facing integration surface.

Common integration sequence

Most product integrations use the APIs in this order:

  1. Configure Stripe credentials and product mappings through the portal setup surface.
  2. Start checkout from your backend with POST /v1/checkout/session.
  3. Redirect the user to the returned Stripe Checkout URL.
  4. Let Stripe call Licenzy webhook endpoints. Your app should not call those inbound Stripe webhook routes directly.
  5. Read access with POST /v1/access/check or inspect entitlements after webhook processing.
  6. For usage packs, consume units with POST /v1/usage/consume from your backend.

The full integration example shows the same sequence as an end-to-end implementation.

Key guides

PreviousGo live checklist