Skip to content

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.

PKCE
// 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
Authorisation URL (one line, URL-encoded)
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_uri with ?code=…&state=…, or ?error=access_denied&state=… if they declined.
  • Check that state matches what you sent.

3. Exchange the code

Codes work once, for 10 minutes. Client credentials may also be sent as HTTP Basic auth.

POST /oauth/token
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_…
200 OK
{
  "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:

Refresh
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

POST /oauth/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 marketplace by 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

ValuePrefixLifetime
Client IDde_app_Until the app is removed
Client secretde_cs_Shown once
Authorisation codeOnce, within 10 minutes
Access tokende_oat_60 minutes
Refresh tokende_ort_30 days, single use