Developer docs
Management API
A REST 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.
Also in the app: terminal.deventitle.com/docs/api · Machine-readable spec: openapi.json (OpenAPI 3.1)
Base URL: https://terminal.deventitle.com/api/manage/v1
Authentication
Create a token in the panel under Developers → API tokens. Choose its scopes and an optional expiry. The token (de_live_…) is shown once and stored only as a hash. You can revoke it at any time and see when it was last used.
curl https://terminal.deventitle.com/api/manage/v1/me \
-H "Authorization: Bearer de_live_…" \
-H "Accept: application/json" Keep tokens on the server
Store tokens in environment variables on your servers. Never put them in browser code or in the product you ship. A connected app sends its OAuth access token (de_oat_…) the same way.
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. - Other companies’ records don’t exist for your token: you get 404.
- Licence keys are returned only once, in the response that issues them. Look licences up with
POST /licenses/lookup; the key goes in the body, never in a URL.
Errors
{
"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 named in details.required_scope |
| 403 | vendor_suspended | Your company 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). 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 (a unique string up to 100 characters, such as your order ID) on POSTs. If the network fails and you retry with the same key and the same body, you get the first answer back, with the header Idempotent-Replayed: true, instead of issuing twice. Keys are kept for 24 hours. Reusing a key with a different body answers 422 idempotency_key_reused.
Licences
| Call | Scope | Notes |
|---|---|---|
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_idinstead ofcustomer(an existing customer with the same email is reused anyway)supported_untilorlifetime(default: the type’s support period from today)max_activations,channel(stableorbeta),notessales_channel:own_site,marketplace,manualorothersend_email(default false) sends the licence email from DevEntitle
The same call from a Laravel checkout:
$response = Http::withToken(env('DEVENTITLE_TOKEN'))
->withHeaders(['Idempotency-Key' => 'order-'.$order->id])
->post('https://terminal.deventitle.com/api/manage/v1/licenses', [
'product' => 'acme-crm',
'license_type_id' => 12,
'customer' => ['email' => $order->email, 'name' => $order->name],
'external_ref' => (string) $order->id,
'send_email' => true,
]);
$key = $response->json('data.key'); // shown once: store it or show it to the buyer now Products
| Call | Scope | Notes |
|---|---|---|
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 | products:write | Create a licence type (below) |
PATCH /products/{slug}/license-types/{id} | products:write | Change a licence type; only the fields you send change |
Create and update licence types
Set up a product’s plans from your own systems, for example a marketplace adding “Regular” and “Extended” for a company. The rules are the same as the form in the panel.
curl -X POST https://terminal.deventitle.com/api/manage/v1/products/acme-crm/license-types \
-H "Authorization: Bearer de_live_…" \
-H "Content-Type: application/json" \
-d '{
"name": "Regular",
"description": "One end product",
"max_activations": 1,
"support_months": 6,
"prices": [
{"kind": "purchase", "currency": "USD", "amount": 2900},
{"kind": "renewal", "currency": "USD", "amount": 900}
]
}' {
"data": {
"id": 12,
"name": "Regular",
"description": "One end product",
"max_activations": 1,
"support_months": 6,
"lifetime": false,
"updates_after_support": false,
"channel": "stable",
"key_prefix": "ACME",
"is_active": true,
"is_public": true,
"prices": [
{"kind": "purchase", "currency": "USD", "amount": 2900},
{"kind": "renewal", "currency": "USD", "amount": 900}
]
}
} | Field | Rules |
|---|---|
name | Required when creating; up to 100 characters |
description | Optional; up to 255 characters |
key_prefix | 2–10 letters or digits, stored in capitals (acx → ACX). Default: the first four letters or digits of the product slug |
max_activations | Sites or devices per licence; 0 = unlimited. Default 1 |
support_months | 1–120 months of support. Default 12 |
lifetime | true for lifetime support (updates always continue). Setting it back to false without support_months gives 12 months |
updates_after_support | true lets updates continue after support ends (only help stops). Default false |
channel | stable (default) or beta |
is_active | false stops new licences being issued with this type. Default true |
is_public | Whether the type is offered on the storefront. Default true |
prices | Up to 50 entries of kind (purchase or renewal), currency (ISO code) and amount (whole number in minor units). Sending prices replaces the whole list |
# Replace the prices (the other fields stay as they are)
curl -X PATCH https://terminal.deventitle.com/api/manage/v1/products/acme-crm/license-types/12 \
-H "Authorization: Bearer de_live_…" \
-H "Content-Type: application/json" \
-d '{"prices": [{"kind": "purchase", "currency": "EUR", "amount": 2700}]}'
# Stop issuing new licences of this type
curl -X PATCH https://terminal.deventitle.com/api/manage/v1/products/acme-crm/license-types/12 \
-H "Authorization: Bearer de_live_…" \
-H "Content-Type: application/json" \
-d '{"is_active": false}' - The response is the licence type, wrapped in
{"data": {…}}. Use itsidaslicense_type_idwhen you issue a licence; it can issue straight away. - There is no delete: set
is_activetofalseinstead. Licences already issued keep their terms either way. - A product or licence type of another company answers
404; a token withoutproducts:writeanswers403 insufficient_scope.
Customers and activations
| Call | Scope | Notes |
|---|---|---|
GET /customers, GET /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 |
Releases
| Call | Scope | Notes |
|---|---|---|
GET /releases, GET /releases/{id} | releases:read | Filters: product, status |
POST /releases | releases:write | Multipart upload (below) |
POST /releases/{id}/publish | releases:write |
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 be the JSON text instead of a file. Sign the zip first: see Releases and signing.
Orders
| Call | Scope | Notes |
|---|---|---|
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) and in your reports.
Webhook endpoints
| Call | Scope | Notes |
|---|---|---|
GET /webhook-endpoints | webhooks:read | |
POST /webhook-endpoints, DELETE /webhook-endpoints/{id} | webhooks:write | url, events, description; the signing secret is returned once |
See Webhooks for events, payloads and signatures.
Audit log
Everything a token changes appears in your company’s audit log, with the token’s name as the actor. The full machine-readable description is openapi.json (OpenAPI 3.1); most languages can generate a client from it.