Management API
For your own systems: your website's checkout, your billing or CRM, your CI. Issue licences for sales made elsewhere, look them up, manage customers and activations, and upload releases.
Authentication
Create a token in DevEntitle under Developers → API tokens and pick its scopes. It is shown once. Send it on every call:
curl https://terminal.deventitle.com/api/manage/v1/me \ -H "Authorization: Bearer de_live_…" \ -H "Accept: application/json"
Keep tokens on your server (environment variables), never in browser or app code. A connected app uses an OAuth access token (de_oat_…) the same way; see Connected apps.
Scopes
| Scope | Allows |
|---|---|
products:read | See products, licence types and prices |
products:write | Create and change products |
licenses:read | See licences and look them up by key |
licenses:write | Issue licences, extend support, suspend, reinstate and revoke them, and create download links |
customers:read | See customers |
customers:write | Create and change customers |
activations:read | See where licences are activated |
activations:write | Remove activations |
releases:read | See releases |
releases:write | Upload and publish releases |
orders:read | See orders, payments and refunds |
webhooks:read | See webhook endpoints |
webhooks:write | Add and remove webhook endpoints |
Conventions
- JSON in and out. Single resources are wrapped in
{"data": {…}}. - Dates are UTC, ISO 8601:
2026-11-01T09:30:00Z. Money is in minor units (cents, paise) with an ISO currency code. - Records of other companies don't exist as far as your token is concerned: you get
404. - Licence keys are only returned once, in the response that issues them. Look licences up by key with
POST /licenses/lookup(the key goes in the body, never in a URL).
Errors
HTTP 422
{"error": {"code": "validation_failed", "message": "The reason field is required.", "details": {"reason": ["The reason field is required."]}}}
| Status | error.code | Meaning |
|---|---|---|
| 401 | unauthenticated | Missing, wrong, revoked or expired token. |
| 403 | insufficient_scope | The token lacks the scope in details.required_scope. |
| 403 | vendor_suspended | Your account is suspended: reads work, changes don't. |
| 404 | not_found | Doesn't exist, or isn't yours. |
| 409 | invalid_state, no_entitled_release, … | The action doesn't fit the record's current state. |
| 422 | validation_failed, release_rejected, idempotency_key_reused | Fix the request; message says how. |
| 429 | rate_limited | More than 120 calls a minute on this token (the default; DevEntitle can raise it for your company). Wait Retry-After seconds. |
Pagination
Lists are newest first and take ?limit= (1–100, default 25). Pass next_cursor back as ?cursor= for the next page:
{"data": [ … ], "next_cursor": "eyJpZCI6…", "has_more": true}
Idempotency
Send an Idempotency-Key header (any unique string up to 100 characters, e.g. your order ID or a UUID) on POSTs. If the network fails and you retry with the same key and the same body, you get the first answer back (with Idempotent-Replayed: true) instead of a second licence. Keys are kept for 24 hours.
Licences
| Call | Scope | |
|---|---|---|
| GET/licenses | licenses:read | Filters: product (slug), customer_id, customer_email, status, external_ref |
| GET/licenses/{id} | licenses:read | |
| POST/licenses/lookup | licenses:read | Body: license_key |
| POST/licenses | licenses:write | Issue a licence (below) |
| PATCH/licenses/{id} | licenses:write | max_activations (null = the type's), notes |
| POST/licenses/{id}/extend | licenses:write | months, or until (date), or lifetime: true; optional reason |
| POST/licenses/{id}/suspend | licenses:write | reason (shown to the buyer in the product) |
| POST/licenses/{id}/reinstate | licenses:write | optional reason |
| POST/licenses/{id}/revoke | licenses:write | reason; refunded: true marks it refunded |
| POST/licenses/{id}/download-link | licenses:write | Link to the newest release this licence may download; optional minutes (5–1440) |
Issue a licence for a sale made elsewhere
curl -X POST https://terminal.deventitle.com/api/manage/v1/licenses \
-H "Authorization: Bearer de_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001" \
-d '{
"product": "acme-crm",
"license_type_id": 12,
"customer": {"email": "[email protected]", "name": "Ann Buyer", "company": "Buyer Ltd"},
"sales_channel": "own_site",
"external_ref": "order-1001",
"external_amount": 24900,
"external_currency": "USD",
"send_email": true
}'
The response is the licence plus "key", returned this once. Optional fields: customer_id instead of customer (an existing customer with the same email is reused anyway), supported_until or lifetime (default: the type's support period from today), max_activations, channel (stable/beta), notes. sales_channel is own_site, marketplace, manual or other; the sale then shows in your reports. send_email (default false) sends the licence email from DevEntitle.
Products, customers, activations, releases, webhooks
| Call | Scope | |
|---|---|---|
| GET/me | any | Your company and the token's scopes |
| GET/products | products:read | |
| GET/products/{slug} | products:read | Everything a listing needs: details, licence types with prices, published versions with notes |
| GET/products/{slug}/license-types | products:read | |
| POST/products, PATCH/products/{slug} | products:write | The slug can't change once created |
| POST/products/{slug}/license-types, PATCH/products/{slug}/license-types/{id} | products:write | name, description, key_prefix, max_activations (0 = unlimited), support_months or lifetime, updates_after_support, channel, is_active, is_public, prices (list of kind, currency, amount in minor units; replaces the list). Types aren't deleted: set is_active to false. Existing licences keep their terms. |
| GET/customers, /customers/{id} | customers:read | Filter: email |
| POST/customers, PATCH/customers/{id} | customers:write | name, email, company, country, tax_id, address |
| GET/activations | activations:read | Filters: license_id, product, domain, is_development |
| DELETE/activations/{id} | activations:write | Frees the slot |
| GET/releases, /releases/{id} | releases:read | Filters: product, status |
| POST/releases | releases:write | Multipart upload (below) |
| POST/releases/{id}/publish | releases:write | |
| GET/webhook-endpoints | webhooks:read | |
| POST/webhook-endpoints, DELETE/webhook-endpoints/{id} | webhooks:write | url, events, description; the secret comes back once |
Upload a release from CI
curl -X POST https://terminal.deventitle.com/api/manage/v1/releases \ -H "Authorization: Bearer $DEVENTITLE_TOKEN" \ -H "Accept: application/json" \ -F product=acme-crm \ -F [email protected] \ -F [email protected] \ -F notes="$(cat CHANGELOG-1.5.0.md)" \ -F publish=1
The hash and signature are checked exactly as in the panel; a mismatch answers 422 release_rejected with the reason. manifest can also be the JSON text instead of a file. Sign the zip first; see Signing releases.
Orders
| Call | Scope | |
|---|---|---|
| GET/orders | orders:read | Storefront purchases and renewals. Filters: status, product, email, kind |
| GET/orders/{id} | orders:read | Totals in minor units, the gateway payment id, refunds and the receipt number |
Sales you record yourself with POST /licenses are not orders; they show on the licence (sales_channel, external_ref, external_amount).