API quickstart

For developers who want the whole loop in code: from an empty account to a live license and a metered usage event, using only the REST API. Prefer clicking through the UI first? See the Admin path.

Prerequisites

• An API client with the right scopes (see Authentication & scopes). Every plan includes at least one (Oclavex Plans).
• Your API base URL.

Steps

Two different bearers appear below. Steps 1–10 carry the API token from step 1. Steps 11 and 12 are the licensed application talking about its own license, and carry the license token from step 10 instead — an API token is refused there.

1. Get a token — POST /auth/connect/token (client-credentials grant). Ask for the scopes the later calls need: a token carries only the scopes the request asks for, capped to those registered on the credential.
2. Create a product — POST /api/v1/provision/admin/products. It starts in Draft; when it’s ready for customers, publish it — PUT /api/v1/provision/admin/products/{productId}/status?lifecycleStatus=Published.
3. Add a feature — POST /api/v1/provision/admin/products/{productId}/features with a dotted feature code.
4. Meter it — POST /api/v1/provision/admin/products/{productId}/monitored-assets. A feature says what the license grants; a monitored asset is what usage counts against. Its metricName is the {metric} steps 11 and 12 address, so without one there is nothing for them to report to.
5. Create an entitlement — POST /api/v1/provision/admin/entitlements.
6. Decide who may activate it — POST /api/v1/provision/admin/entitlements/{entitlementId}/policies/activation. A new entitlement expects whoever activates to sign in with an identity provider, and an application holding only its own API credential cannot. Send { "requiredAuthenticationLevel": "Anonymous" } to make the activation code itself the credential — which is what an unattended install needs, and worth choosing deliberately, because it is the answer to “who may redeem this code”.
7. Attach the product — POST /api/v1/provision/admin/entitlements/{entitlementId}/products/{productId}. An entitlement carries no product of its own, so this is the step that decides what the license actually grants. To sell a whole suite instead, attach that — POST /api/v1/provision/admin/entitlements/{entitlementId}/suites/{suiteId}.
8. Publish the entitlement — POST /api/v1/provision/admin/entitlements/{entitlementId}/enable-activations.
9. Issue an activation code — POST /api/v1/provision/operational/entitlements/{entitlementId}/activation-codes.
10. Activate a license — POST /api/v1/provision/activations/license with the code and a device fingerprint. Keep the returned licenseToken: it is the bearer for the two calls below, and its jti claim is the session id they address.
11. Report usage — POST /api/v1/provision/usage/try-consume/{sessionId}/{metric}?amount=1. The response is the decision and the metric’s state after it.
12. Read it back — GET /api/v1/provision/usage/{sessionId}/{metric}/usage.

Example: the token, the activation policy and the bearer swap

api.example.com stands in for your tenant endpoint — replace it with your own host.

# 1. Get a token. Without `scope` the token carries none, and step 2 is refused with 403.
curl -X POST https://api.example.com/auth/connect/token \
  -d grant_type=client_credentials \
  -d client_id=$ID -d client_secret=$SECRET \
  -d scope="provision.product.* provision.entitlement-adm.* provision.entitlement-oper.*"

# 6. Let the activation code be the credential. Skip this and step 10 answers 403,
#    asking whoever is activating to sign in first.
curl -X POST https://api.example.com/api/v1/provision/admin/entitlements/$ENTITLEMENT_ID/policies/activation \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "requiredAuthenticationLevel": "Anonymous" }'

# 10. Activate a license — still the API token.
curl -X POST https://api.example.com/api/v1/provision/activations/license \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "activationCode": "…", "fingerprint": "…" }'

# 11. Report usage — the license token from step 10, not the API token.
#     Its `jti` claim is the session id in the path.
curl -X POST "https://api.example.com/api/v1/provision/usage/try-consume/$SESSION_ID/$METRIC?amount=1" \
  -H "authorization: Bearer $LICENSE_TOKEN"

Full request and response schemas are in the REST API reference.