Authentication

Oclavex has two credential models, and knowing which one a call uses removes most integration confusion:

Model	Who holds it	Authenticates
OAuth client credentials	Your backend / back-office code	admin/* and operational/* endpoints — catalog authoring, entitlement management, code issuance, reporting
Activation code + device fingerprint → license session token	Your shipped application	The runtime surface — activation, session renew/check-in/release, usage reporting

Your backend is a trusted server and identifies itself with a secret. Your shipped application is not — it never carries an API secret; it earns a signed license token by presenting an activation code and a device fingerprint.

API clients and tokens

Register a client in the portal under Settings → API credentials (guide). The secret is shown once at creation; grant the client only the scopes it needs.

Depends on your plan

Every plan includes at least one client credential; the number you can register scales with your plan. Free is machine-to-machine only — interactive clients, meaning public clients and the authorization-code flow, need Basic or above (what depends on your plan).

Exchange the id and secret for a token, then carry it as a bearer. Ask for the scopes the token needs: it carries only the scopes the request asks for, capped to those registered on the client, so a request that omits scope yields a token that is refused by every admin/* endpoint. api.example.com stands in for your tenant endpoint — replace it with your own host.

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.*"

curl https://api.example.com/api/v1/provision/admin/products \
  -H "authorization: Bearer $TOKEN"

Tokens are short-lived — cache one and refresh on expiry rather than requesting per call. Scopes may use wildcards and are checked per HTTP verb; the catalog is in Auth & scopes.

License session tokens

The activation endpoints are anonymous — no bearer token needed:

curl -X POST https://api.example.com/api/v1/provision/activations/jwt \
  -H "content-type: application/json" \
  -d '{ "activationCode": "ABC123-DEF456-GHI789", "fingerprint": "device-fingerprint-hash" }'

The response is a signed JWT — the license itself. It authenticates every session-scoped call that follows: POST /activations/{sessionId}/renew, /check-in, /release, and the usage endpoints.

Retries are safe

Re-activating with the same activation code and fingerprint returns the existing session instead of creating a duplicate, so a client can retry a failed network call without leaking seats.

Use POST /activations/license instead of /jwt when the client also needs the metadata: provider info, legal notices, licensed product ids, and the public key for verifying the token offline.

Note

Only /jwt and /license are anonymous. Not everything under the /activations prefix is an activation endpoint — POST /activations/admission/check is the sign-up admission check used by the platform during account sign-up, and it requires its own scope (provision.activation-admission.check).

Interactive-user activation

When your application has a signed-in user (a SaaS app, a portal), set useInteractiveUser: true on the activation request and send the user’s token. The server resolves entitlements assigned to that user; the activation code becomes optional when the user has exactly one. This is how you license per-user without distributing codes at all — assign the entitlement to the user and let sign-in do the rest. The same assignment powers the end-user portal, where users see and activate their licenses themselves.

In the .NET SDK

The SDK abstracts both models behind IAuthenticationProvider. Ready-made providers ship in Revenusion.MonetizeIt.Client.AspNetCore:

• ClientCredentialsAuthentication — the backend model: discovers the token endpoint, requests and caches tokens, refreshes on expiry.
• BearerTokenLicenseApiAuthentication — the runtime model: attaches the license session token to session-scoped calls.
• AnonymousAuthentication — for the activation calls themselves.

LicenseClientBuilder.UseInteractiveUserActivation() switches the .NET SDK to interactive-user activation.

If you bring your own IAuthenticationProvider, implement ILicenseTokenSink on it and the SDK feeds it the license session token on every successful activation and refresh — your provider can then present the current session token on session-scoped calls without extra code to pass the token around.

What to protect

• Client secrets stay on your servers. Never embed one in a desktop or mobile build — that’s what the license-session model is for.
• License tokens are bearer credentials for the session; don’t log them.
• Rotation and storage guidance is in Credentials & secrets.