Credentials & secrets

Four kinds of secret material exist in an Oclavex integration. Each has its own rotation procedure; none needs to be shared between them.

API client secrets

Created under Settings → API credentials (guide). Every plan includes at least one API client, so your backend authenticates with client credentials; higher plans raise the limit (Oclavex Plans).

• The secret is shown once, at creation. Store it in your secret manager; if it’s lost, Rotate Secret issues a new one — there is no way to read it back.
• Grant each client the narrowest scopes that work (scope catalog) and use separate clients per system, so one leaked credential reaches little and is disabled in one place. Disable is the soft switch: it blocks new token issuance, but tokens already issued stay valid until they expire naturally. An issued access token lives up to an hour and nothing recalls it, so Disable on its own leaves a window that long. On a confirmed leak, Delete the client or Rotate Secret — those stop the leaked secret at once — and treat the hour as the exposure you still have to account for.
• Client secrets belong on servers only. A desktop or device build never carries one — the license-session model exists so it doesn’t have to.

Webhook signing secrets

Each subscription has an HMAC secret (minimum 32 bytes) used to sign every delivery.

• Rotate from the portal (Settings → Webhooks) or POST /api/v1/webhooks/admin/subscriptions/{id}/secret.
• Rotation has an overlap window: deliveries carry signatures under both the old and new secret until it closes, so a receiver that checks all candidate signatures drops nothing during the roll.
• Rotations are recorded in the audit trail.

License tokens and the signing key

Licenses are RSA-signed JWTs.

• Devices hold only the public key — pin it in the .NET SDK (fetch once from GET /api/v1/provision/admin/providers/license-signing-key, or list every live key from GET .../providers/license-signing-keys if you’re pinning a set for rotation, below). Nothing that ships to a customer machine can mint or alter a license.
• The same key signs offline activation responses and usage receipts, so air-gapped devices verify artifacts with the key they already trust.
• License tokens are bearer credentials for their session: don’t log them, and release the session (ReleaseSessionAsync / POST .../release) when done.
• The SDK’s on-disk license cache is encrypted at rest, on by default — see at-rest encryption of the cache. It’s a different protection from the signature above: the signature stops a forged or altered license; cache encryption stops a copied cache file from being read on another machine.

Rotating the license signing key

Unlike the other secrets on this page, you can’t just issue a new signing key and move on — every license already on a customer’s machine was signed by the old one, and swapping keys must never invalidate them mid-lease. Settings → License signing keys (admin-only) drives this as a four-step, no-downtime cycle:

1. Publish a new key. It exists, but signs nothing yet — new activations keep using the current key.
2. Ship a build that pins both keys — the current one and the one you just published — via the SDK’s multi-key UsePublicKey. Wait until most of your fleet runs this build.
3. Promote the new key. The provider now signs everything — new licenses, offline activation responses, usage receipts — with it. Licenses the old key already issued keep validating, because clients still pin that key too.
4. Retire the old key once nothing depends on it any longer. This is the one irreversible step: retiring stops the key verifying anything it signed, immediately. The portal refuses to retire a provider’s only live key, and won’t let you retire the currently-active one directly — promote a replacement first.

A client that only pins one key (the pre-rotation default) isn’t rejected on key_id grounds: a bare pinned key verifies a license carrying any key_id, so the licenses its key already signed keep validating. What it cannot verify is anything the new key signs after promotion — ship such clients the two-key build of step 2 before their license is next re-signed.

Access tokens

• Tokens from the client-credentials grant are short-lived by design. Cache one and refresh on expiry (the SDK’s authentication providers do this); don’t request a fresh token per call.
• Keep tokens out of logs, URLs and error reports — they’re Authorization header material only.