Reference

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

The REST API reference is a separate document with its own navigation. It is generated from the OpenAPI spec: one page per operation, grouped by area (licensing, entitlements, sessions, products, usage and admin), plus the request and response schemas. Its sidebar leads back to these docs, and search covers both.

• 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, and free, reset or block devices.
provision.session-adm.*	List license sessions (activations) across the account.
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.
provision.billing-events.write	Single verb: post subscription, account and credit events from your own billing system — see Billing events.

Other areas

Scope	Grants
webhooks.integrator	Manage subscriptions through the integrator API (e.g. Zapier). The only grantable webhooks scope.
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.
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. The onboarding.* scopes, which manage your organization’s environments and tenant settings, aren’t grantable either: administrators hold them through their role and use them in the portal.

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.