DevEntitle

Connected apps

For apps that many companies connect to, such as a marketplace or a reseller site. Each company approves your app on a DevEntitle consent screen, choosing which of its data you may use. You then act for that company only, within those scopes, through the Management API.

1. Get registered

Apps are registered and approved by DevEntitle staff. Write to [email protected] with the app's name, website, redirect URIs and the scopes it needs. You receive a client_id (de_app_…) and a client_secret (de_cs_…). Keep the secret on your server.

2. Send the company to the consent screen

Create a random code_verifier (43–128 characters) and keep it in the user's session. Its challenge is base64url(sha256(code_verifier)) without padding. Then redirect to:

https://terminal.deventitle.com/oauth/authorize?response_type=code
  &client_id=de_app_…
  &redirect_uri=https://market.example.com/oauth/callback
  &scope=products:read licenses:read licenses:write
  &state=<random, checked on return>
  &code_challenge=<challenge>
  &code_challenge_method=S256

The person signs in to DevEntitle if needed, picks the company (only owners and admins can connect apps) and allows or denies. They come back to your redirect_uri with ?code=…&state=…, or ?error=access_denied&state=…. The redirect URI must exactly match a registered one. PKCE with S256 is required.

3. Exchange the code

curl -X POST https://terminal.deventitle.com/oauth/token \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=https://market.example.com/oauth/callback \
  -d code_verifier=<code_verifier> \
  -d client_id=de_app_… \
  -d client_secret=de_cs_…
{
  "token_type": "Bearer",
  "access_token": "de_oat_…",
  "expires_in": 3600,
  "refresh_token": "de_ort_…",
  "scope": "products:read licenses:read licenses:write",
  "vendor": {"id": 42, "slug": "acme-software", "name": "Acme Software"}
}

Codes work once, for 10 minutes. Store the tokens per company (vendor.id). Client credentials may also be sent as HTTP Basic auth.

4. Call the API, refresh when needed

Use Authorization: Bearer de_oat_… on the Management API. Access tokens last 60 minutes. Get a new pair with the refresh token:

curl -X POST https://terminal.deventitle.com/oauth/token \
  -d grant_type=refresh_token -d refresh_token=de_ort_… \
  -d client_id=de_app_… -d client_secret=de_cs_…

Refresh tokens last 30 days and work once: always store the new one. Using an old refresh token again (or a code twice) is treated as a leak, and every token of that connection is revoked; the company then has to connect again.

What a connection can and can't do

  • It acts for the one company that approved it, and only within the scopes that company granted (and that your app is allowed to ask for).
  • Licences you issue are marked as coming from your app, with sales channel marketplace unless you say otherwise.
  • Webhook endpoints you add with POST /webhook-endpoints belong to your app: you see only your own, and you only receive events you could read through the API.
  • The company can revoke you at any time under Developers → Connected apps. Tokens stop working at once and your webhook endpoints are switched off.
  • To end a connection yourself: POST https://terminal.deventitle.com/oauth/revoke with token, client_id and client_secret.

Scopes

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