Developer docs
Connected apps (OAuth 2)
For apps many companies connect to, such as marketplaces and reseller sites. Each company approves your app on a DevEntitle consent screen. Your app then acts for that company only, within the permissions it granted, through the Management API.
Also in the app: terminal.deventitle.com/docs/oauth · Machine-readable spec: openapi.json (OpenAPI 3.1)
Overview
DevEntitle uses the OAuth 2 authorisation-code flow with PKCE (S256 required). The company picks which of its companies to connect and sees exactly which scopes you ask for. You receive per-company access and refresh tokens and call the Management API with them, exactly as with an API token.
1. Get registered
Apps are registered and approved by DevEntitle staff. Write to [email protected] with:
- your app’s name and website
- its redirect URIs (they must match exactly when used)
- the scopes it needs
You receive a client_id (de_app_…) and a client_secret (de_cs_…, shown once).
2. Send the company to the consent screen
Create a random code_verifier of 43–128 characters. The challenge is base64url(sha256(code_verifier)) without padding.
// Node.js: create the PKCE verifier and challenge
import { randomBytes, createHash } from 'node:crypto';
const verifier = randomBytes(48).toString('base64url'); // 64 characters
const challenge = createHash('sha256').update(verifier).digest('base64url'); // no padding 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 - Only company owners and admins can connect apps, and owners need two-factor sign-in.
- The person returns to your
redirect_uriwith?code=…&state=…, or?error=access_denied&state=…if they declined. - Check that
statematches what you sent.
3. Exchange the code
Codes work once, for 10 minutes. Client credentials may also be sent as HTTP Basic auth.
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"}
} Store tokens per company, keyed by vendor.id.
4. Call the API and refresh
Send Authorization: Bearer de_oat_… to the Management API. Access tokens last 60 minutes. Refresh them with grant_type=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 work once
Refresh tokens last 30 days and can be used only once: always store the new one you get back. Reusing an old refresh token or a code is treated as a leak and revokes every token of that connection.
5. Revoke
curl -X POST https://terminal.deventitle.com/oauth/revoke \
-d token=de_ort_… \
-d client_id=de_app_… -d client_secret=de_cs_… What a connection can and can’t do
- It acts for one company, within the scopes that company granted.
- Licences it issues are marked as coming from your app, with sales channel
marketplaceby default. - Webhook endpoints it adds belong to it, and only receive events it could read.
- The company can revoke the connection at any time under Developers → Connected apps. Tokens stop at once and its webhooks are switched off. Licences it issued stay valid.
Token reference
| Value | Prefix | Lifetime |
|---|---|---|
| Client ID | de_app_ | Until the app is removed |
| Client secret | de_cs_ | Shown once |
| Authorisation code | Once, within 10 minutes | |
| Access token | de_oat_ | 60 minutes |
| Refresh token | de_ort_ | 30 days, single use |