TransaktDocs

Getting started

From an empty workspace to your first entitlement call in five steps.

Your application talks to the product API on the api host of the platform (for this site's environment, https://api.test.konsolutelab.uk). Every call is made as an API client: one of your applications, registered in your Admin Portal, that belongs to your partner workspace and can only read your own products and customers.

The examples use shell variables: TRANSAKT_API for the API origin, and TENANT_ID, CLIENT_ID, CLIENT_SECRET and API_APP_ID for your Entra application.

export TRANSAKT_API="https://api.<platform-domain>"

Create an API client

In your Admin Portal, open Partner settings › Integrations › API clients and choose Add API client (you need the Integration manager or Partner administrator role).

  • Name: your application, for example Contoso Planner (production).
  • Products: all your products, or only the ones this application may ask about.
  • Scopes: Entitlements: read (entitlements:read), Catalogue: read (catalogue:read) and, to report Marketplace usage, Metered usage: write (usage:write).
  • Rate limit per minute (optional, 60 to 6,000), within your plan's quota.

Use one API client per application and environment, so you can disable or rotate one without touching the others.

Give it a credential

An API client has one or more credentials. Prefer an Entra application; API keys exist for applications that cannot use Microsoft Entra.

  1. In your own Microsoft Entra tenant, register (or reuse) your application and give it a client secret or certificate.
  2. Grant it the Transakt API's application permissions that match the scopes: Entitlement.Read.All, Catalogue.Read.All, Usage.Write.All, and have a tenant administrator grant admin consent. (If the Transakt API is not listed under APIs my organization uses, an administrator creates its service principal first, for example az ad sp create --id {apiAppId}.)
  3. On the API client, choose Add Entra application and enter the Application (client) id and the Tenant id your application's tokens are issued in. The credential is pending verification and the dialog shows a one-time challenge, valid for 24 hours.
  4. Prove that you control the application: call POST /api/v1/client-credentials/verify from it, with a client-credentials token (step 3 below) and the challenge. The credential becomes Active.
curl -X POST "$TRANSAKT_API/api/v1/client-credentials/verify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "challenge": "<the challenge from the Admin Portal>" }'

Holding an app role authorises nothing by itself: Transakt accepts the token only from a verified credential of an enabled API client.

Get a token (Entra)

Ask Microsoft Entra for a token with the client credentials grant, in the tenant you registered, for the Transakt API (api://{apiAppId}/.default, where {apiAppId} is the application id of the Transakt API for your environment; the Admin Portal shows it, with the whole scope ready to copy, on the API clients page under Connect your application):

TOKEN=$(curl -s -X POST "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" \
  -d scope="api://$API_APP_ID/.default" | jq -r .access_token)

In code, use the Microsoft Authentication Library (MSAL) or Azure.Identity / @azure/identity, which cache and renew tokens for you.

Call the entitlement API

Ask what a customer's tenant holds for one of your products. The tenant is the customer's Microsoft Entra tenant id; the product is your product's id (slug).

curl "$TRANSAKT_API/api/v1/entitlements/72f988bf-86f1-41af-91ab-2d7cd011db47?product=planner" \
  -H "Authorization: Bearer $TOKEN"
# or: -H "X-Api-Key: $TRANSAKT_API_KEY"
{
  "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
  "product": { "slug": "planner", "name": "Planner" },
  "status": "Active",
  "accessLevel": "Full",
  "plans": [{ "slug": "business-monthly", "name": "Business (monthly)" }],
  "plan": { "slug": "business-monthly", "name": "Business (monthly)" },
  "edition": { "slug": "business", "name": "Business", "rank": 2 },
  "licenceModel": "TenantWide",
  "licenceOutcome": "Licensed",
  "capabilities": { "reports.export": true, "sso": true },
  "quantity": null,
  "validUntil": "2027-09-30T23:59:59.000Z",
  "isTrial": false,
  "trialEndsAt": null,
  "cancelledAt": null,
  "sources": ["Marketplace"],
  "marketplace": { "sourceName": "contoso", "offerId": "planner-saas" },
  "version": 7,
  "evaluatedAt": "2026-10-08T09:30:00.000Z"
}

A tenant that never bought the product is not an error: the answer is 200 with status: "None" and accessLevel: "None".

Read the edition and capabilities

Decide access from three fields:

  • accessLevel: Full (use the product), ReadOnly (suspended: let users see but not change their data, if your product supports it) or None.
  • edition: the functional tier (slug and rank are stable; name is for display). A tenant holding several plans gets the highest-ranked edition.
  • capabilities: the feature switches the tenant's active plans include (a switch is on when any active plan turns it on). Numeric limits are on each plan in the catalogue; seat counts are in quantity.

When licenceOutcome is NotApplicable, the licence is decided per user (seats or Microsoft-managed licences): ask the eligibility endpoint for each user.

Responses carry an ETag; send it back as If-None-Match to get a cheap 304 when nothing changed, and subscribe to webhook events instead of polling.

Next steps

Transakt documentation

Sell your software through Microsoft Marketplace and directly, and let your application know what each customer may use.

Products, editions and plans

How your catalogue is organised, and where capabilities live.

On this page

Create an API clientGive it a credentialGet a token (Entra)Call the entitlement APIRead the edition and capabilitiesNext steps