Skip to main content

Issue a License from a Subscription

Use this Management operation when your Vendor automation has an existing Customer Subscription and needs to issue its canonical License and human key.

POST /api/v1/licenses/subscription-issues
Authorization: Bearer <service-account-token>
Idempotency-Key: <unique-operation-key>
X-Correlation-Id: <correlation-id>
Content-Type: application/json
{
  "customerSubscriptionId": "019b0000-0000-7000-8000-000000000101",
  "correlationId": "019b0000-0000-7000-8000-000000000102"
}

The service account needs licenses.manage. Tenant and actor identity come from the authenticated context. Do not send tenantId, actor, Product, Customer, OfferVersion, Policy, validity, License code, or key material; unknown request fields are rejected.

First success and replay​

The first durable commit returns 201 Created. plaintextKey is a shown-once secret; copy it directly to an approved secret store and never log it.

{
  "licenseId": "019b0000-0000-7000-8000-000000000201",
  "licenseCode": "LIC-<server-generated-id>",
  "keyMaterialRefId": "019b0000-0000-7000-8000-000000000202",
  "snapshotId": "019b0000-0000-7000-8000-000000000203",
  "snapshotVersion": 1,
  "snapshotHash": "<lowercase-sha256>",
  "maskedKey": "7K3M-••••-••••-••••-ABCD",
  "plaintextKey": "<shown-once-secret>",
  "issueMode": "Subscription",
  "isIdempotentReplay": false
}

Retry the same effective request with the same Idempotency-Key. An exact replay returns 200 OK, the same references and mask, and:

{
  "plaintextKey": null,
  "isIdempotentReplay": true
}

If the first response was lost after commit, plaintext cannot be recovered by replay. Use a separately authorized key rotation when a new secret is needed.

Errors​

Every error uses the standard ErrorResponse. SDK mapping below uses the recommended public exception category.

HTTP / codeRetrySDK categoryClient action
400 license_issue.invalid_requestNoValidationExceptionFix the body or Idempotency-Key.
404 license_issue.subscription_not_foundNoNotFoundExceptionRecheck the tenant-scoped Subscription ID.
409 license_issue.source_conflictNoConflictExceptionRefresh Subscription/Offer/Policy data and resolve the inconsistency.
409 license_issue.not_issuableNoConflictExceptionMove the Subscription/OfferVersion to an issuable state.
409 license_issue.idempotency_conflictNoIdempotencyConflictExceptionUse the original payload or a new key for a new operation.
409 license_issue.persistence_conflictYesConflictExceptionRetry with backoff and the same key.
503 license_issue.audit_unavailableYesServiceUnavailableExceptionRetry with backoff and the same key.
500 license_issue.stored_result_invalidNoServerContractExceptionStop retrying and contact platform support with correlationId.

Authentication failures are 401 unauthorized; missing licenses.manage is 403 forbidden.

Related​