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
marketplaceunless you say otherwise. - Webhook endpoints you add with
POST /webhook-endpointsbelong 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/revokewithtoken,client_idandclient_secret.
Scopes
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 |