Reference

The external contract: the REST API, webhook events, error codes, scopes and the glossary.

• REST API — generated from the OpenAPI spec, grouped by area: licensing, entitlements, sessions, products, usage and admin.
• Webhook events — the full catalog of emittable events, the envelope, and the signing scheme.
• Error codes — the application/problem+json contract (RFC 9457).
• Glossary — terms used across the docs.

Auth & scopes

Oclavex uses OAuth 2.0 / OIDC. Your backend authenticates with the client-credentials grant; interactive users sign in through the browser (authorization code with PKCE). The runtime activation endpoints don’t use scopes at all — they’re either anonymous or authenticated by the license session token. The full walkthrough is in Authentication.

Scope format

Scopes are space-separated in the token’s scope claim and follow <area>.<resource>.<verb>. Matching is wildcard-aware per segment and verb-granular: provision.* grants everything under provisioning, provision.product.* all product verbs, provision.product.read just reads. A client only receives the scopes granted to it in Settings → API credentials; requesting more at the token endpoint doesn’t add them.

Provisioning scopes

Each family below has create, read, update, delete verbs plus a .* wildcard, unless noted.

Scope family	Grants
provision.product.*	Author the catalog: products, versions, features, monitored assets.
provision.entitlement-adm.*	Author entitlements and entitlement offers; publish and cancel.
provision.entitlement-oper.*	Day-to-day operations on entitlements: issue activation codes, renew subscriptions, restart trials.
provision.session-adm.*	Administer license sessions across the account: list activations, release seats.
provision.session.*	A signed-in user’s own license sessions (self-service).
provision.usage.*	Report and read usage transactions and metered consumption.
provision.asset-usage-adm.*	Administer usage tracking: monitored assets, quotas, plans.
provision.asset-balance-opr.*	Operate credit balances: top up, withdraw, suspend and resume.
provision.catalog.export / provision.catalog.import	Export or import catalog data (e.g. sandbox → production).
provision.activation-admission.check	Single verb: the sign-up admission check called by the identity service.

Other areas

Scope	Grants
webhooks.read / webhooks.write	Read and manage webhook subscriptions, deliveries and secrets.
webhooks.dlq.read / webhooks.dlq.write	Inspect and requeue failed deliveries (the failed-delivery queue).
webhooks.integrator	Manage subscriptions through the integrator API (e.g. Zapier).
privacy.read / privacy.write	List and file data-subject requests.
identity.clients.read / .write / .delete	Manage the OAuth clients under Settings → API credentials — including secret rotation — via the API.
organization.identity.create / .read / .update / .delete	Manage the user directory.
organization.identity.self	A user reading and updating their own profile only.
organization.identity.approve	Flip a user’s approved/blocked flags — nothing else.
data.metrics.read / .write	Read and write metric data (dashboards, reporting pipelines).
data.audit.read	Read the audit trail.
data.ratings.read	Read collected feature-rating responses.
data.user-activity.read	Read user-activity history.
onboarding.create / .read / .update / .delete	Drive and inspect tenant onboarding.
api.configuration	Read API configuration metadata.
salesforce.cdc.read / .write	The Salesforce connector’s inbound change-event feeds.
salesforce.connectors.read / .write	Register and manage Salesforce connectors.
salesforce.outbound.read / .write	The Salesforce outbound write-back queue.

Two platform-reserved scopes — oclavex.sysadmin and no-license-required — exist in the catalog but are never grantable to tenant clients.

Authorization also honors a permissions claim carrying role bundles alongside scope — a token can satisfy an endpoint through either.

What portal roles hold

Portal users get a default scope set from their role: Admin holds the full admin surface; Sales adds entitlement authoring and operations, credit-balance operations and customer creation on top of the read-only scopes every role holds; Support adds entitlement operations, credit-balance operations and user approval; Viewer is read-only plus organization.identity.self (own profile updates). User tokens are always capped at what the role allows.