Skip to content

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.

Who am I?
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

ScopeAllows
products:readSee products, licence types and prices
products:writeCreate and change products
licenses:readSee licences and look them up by key
licenses:writeIssue licences, extend support, suspend, reinstate and revoke them, and create download links
customers:readSee customers
customers:writeCreate and change customers
activations:readSee where licences are activated
activations:writeRemove activations
releases:readSee releases
releases:writeUpload and publish releases
orders:readSee orders, payments and refunds
webhooks:readSee webhook endpoints
webhooks:writeAdd 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

422 Unprocessable Content
{
  "error": {
    "code": "validation_failed",
    "message": "The reason field is required.",
    "details": {"reason": ["The reason field is required."]}
  }
}
Statuserror.codeMeaning
401unauthenticatedMissing, wrong, revoked or expired token
403insufficient_scopeThe token lacks the scope named in details.required_scope
403vendor_suspendedYour company is suspended: reads work, changes don’t
404not_foundDoesn’t exist, or isn’t yours
409invalid_state, no_entitled_release, …The action doesn’t fit the record’s current state
422validation_failed, release_rejected, idempotency_key_reusedFix the request; message says how
429rate_limitedMore 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.

A page of results
{"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

CallScopeNotes
GET /licenseslicenses:readFilters: product (slug), customer_id, customer_email, status, external_ref
GET /licenses/{id}licenses:read
POST /licenses/lookuplicenses:readBody: license_key
POST /licenseslicenses:writeIssue a licence (below)
PATCH /licenses/{id}licenses:writemax_activations (null = the type’s), notes
POST /licenses/{id}/extendlicenses:writemonths, or until (date), or lifetime: true; optional reason
POST /licenses/{id}/suspendlicenses:writereason (shown to the buyer in the product)
POST /licenses/{id}/reinstatelicenses:writeOptional reason
POST /licenses/{id}/revokelicenses:writereason; refunded: true marks it refunded
POST /licenses/{id}/download-linklicenses:writeLink to the newest release this licence may download; optional minutes (5–1440)

Issue a licence for a sale made elsewhere

POST /licenses
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 or beta), notes
  • sales_channel: own_site, marketplace, manual or other
  • send_email (default false) sends the licence email from DevEntitle

The same call from a Laravel checkout:

Laravel
$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

CallScopeNotes
GET /meanyYour company and the token’s scopes
GET /productsproducts:read
GET /products/{slug}products:readEverything a listing needs: details, licence types with prices, published versions with notes
GET /products/{slug}/license-typesproducts:read
POST /products, PATCH /products/{slug}products:writeThe slug can’t change once created
POST /products/{slug}/license-typesproducts:writeCreate a licence type (below)
PATCH /products/{slug}/license-types/{id}products:writeChange 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.

POST /products/acme-crm/license-types
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}
    ]
  }'
201 Created
{
  "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}
    ]
  }
}
FieldRules
nameRequired when creating; up to 100 characters
descriptionOptional; up to 255 characters
key_prefix2–10 letters or digits, stored in capitals (acx → ACX). Default: the first four letters or digits of the product slug
max_activationsSites or devices per licence; 0 = unlimited. Default 1
support_months1–120 months of support. Default 12
lifetimetrue for lifetime support (updates always continue). Setting it back to false without support_months gives 12 months
updates_after_supporttrue lets updates continue after support ends (only help stops). Default false
channelstable (default) or beta
is_activefalse stops new licences being issued with this type. Default true
is_publicWhether the type is offered on the storefront. Default true
pricesUp to 50 entries of kind (purchase or renewal), currency (ISO code) and amount (whole number in minor units). Sending prices replaces the whole list
PATCH /products/acme-crm/license-types/12
# 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 its id as license_type_id when you issue a licence; it can issue straight away.
  • There is no delete: set is_active to false instead. Licences already issued keep their terms either way.
  • A product or licence type of another company answers 404; a token without products:write answers 403 insufficient_scope.

Customers and activations

CallScopeNotes
GET /customers, GET /customers/{id}customers:readFilter: email
POST /customers, PATCH /customers/{id}customers:writename, email, company, country, tax_id, address
GET /activationsactivations:readFilters: license_id, product, domain, is_development
DELETE /activations/{id}activations:writeFrees the slot

Releases

CallScopeNotes
GET /releases, GET /releases/{id}releases:readFilters: product, status
POST /releasesreleases:writeMultipart upload (below)
POST /releases/{id}/publishreleases:write
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 be the JSON text instead of a file. Sign the zip first: see Releases and signing.

Orders

CallScopeNotes
GET /ordersorders:readStorefront purchases and renewals. Filters: status, product, email, kind
GET /orders/{id}orders:readTotals 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

CallScopeNotes
GET /webhook-endpointswebhooks:read
POST /webhook-endpoints, DELETE /webhook-endpoints/{id}webhooks:writeurl, 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.