API reference
The product API, generated from its OpenAPI document.
The product API is served on the api host (for this site's environment, https://api.test.konsolutelab.uk) under /api/v1. It answers your applications about your customers' entitlements and your catalogue, and takes metered usage. Every call runs in your partner workspace, resolved from the credential: the same URL never answers about another partner's products or customers.
Authentication
Send one of:
| Credential | Header |
|---|---|
| Entra application (preferred) | Authorization: Bearer <client-credentials token for api://{apiAppId}> with the matching app role |
| API key | X-Api-Key: transakt_{env}_{keyId}_{secret} |
| Acting for a signed-in user | The user's delegated token (scope Entitlement.Read), with the API key or from a verified Entra application |
| Endpoints | API client scope | App role (Entra tokens) |
|---|---|---|
| Entitlements and eligibility | entitlements:read | Entitlement.Read.All |
| Catalogue | catalogue:read | Catalogue.Read.All |
| Metered usage | usage:write | Usage.Write.All |
An Entra token needs both the API client's scope and the app role. Any refused credential answers 401 auth.credentials_invalid without saying which part failed; see Getting started.
Conventions
- JSON with camelCase names; enumeration values are PascalCase strings; timestamps are UTC (
2026-10-01T09:30:00.000Z); nullable members are always present. - Additive changes only within
/api/v1: ignore unknown members, tolerate unknown enumeration values (an unknownlicenceOutcomeisUnconfirmed, an unknownaccessLevelthe most restrictive) and handle unknown error codes by their HTTP status. A breaking change becomes/api/v2, with at least 12 months' notice; deprecations are announced withDeprecationandSunsetheaders. - Rate limits are per API client within your plan's quota. Responses carry
RateLimit-PolicyandRateLimitheaders; a rejection is429 request.rate_limitedwithRetry-After. - Caching: read endpoints return an
ETag; revalidate withIf-None-Matchfor a304. - Errors are problem details with a stable
code.
The OpenAPI document is served at /openapi/product.json on the API host, so you can generate a client from it.
Handling errors
Problem details responses, stable codes, and what to retry.
Check whether a user may use a product (by email) POST
As the GET form, with the question in the body: `userObjectId` or `email`. An email is resolved to the one active member of the organisation that holds the tenant; otherwise the answer is `422 entitlement.user_not_resolved` and you should ask by object id. Errors: [`request.validation_failed`](/errors/request.validation_failed/), [`api_client.product_not_allowed`](/errors/api_client.product_not_allowed/), [`entitlement.user_tenant_mismatch`](/errors/entitlement.user_tenant_mismatch/), [`entitlement.user_not_resolved`](/errors/entitlement.user_not_resolved/), [`product.not_found`](/errors/product.not_found/), [`plan.not_found`](/errors/plan.not_found/), [`auth.credentials_invalid`](/errors/auth.credentials_invalid/), [`auth.forbidden`](/errors/auth.forbidden/), [`request.rate_limited`](/errors/request.rate_limited/).