Allure Create publishing: V1 and V2 coexistence

Allure Connect continues to support its public V1 package, launch, session, dispatch, reporting, and webhook APIs. The Create V2 publishing contract is an additional, signed product-to-product path for Allure Create. It is not a replacement URL for existing customer API integrations.

Which version should I use?

POST /api/v2/connect-packages is an internal product surface. It requires a verified Create-to-Connect workspace link, a signed short-lived portfolio proof, and an internal-product API key. Customer API keys are not silently upgraded to that contract.

Current availability and workspace eligibility

V1 is the generally available customer contract. The V2 routes and OpenAPI contract are publicly documented on the Connect app host, but V2 remains an internal product-to-product surface in a controlled rollout; it is not a generally available customer API.

Connect accepts a new V2 publish only when both server-side controls pass:

1. CONNECT_CREATE_PUBLISH_V2_ENABLED is exactly true; and
2. the request's exact { tenantId, allureWorkspaceId } pair appears in CONNECT_CREATE_PUBLISH_V2_WORKSPACE_ALLOWLIST_JSON.

The flag defaults to false. The allowlist defaults to empty, and missing, malformed, duplicate, oversized, or non-matching values fail closed. The exact pair is checked before reserving a new receipt or binding a new hosted conversion. Existing accepted receipts and active hosted conversions remain replayable and reconcilable after the controls are disabled. A hosted stage whose exact idempotency key was already durably bound may finish activation and start its one meter after a flag flip; this completes accepted work without allowing a new binding. The Furness hard denial still overrides that lifecycle.

The canonical and historical Furness/FidesAcademy tenant identities are a server-side hard denial independent of configuration. Production keeps V2 off and the allowlist empty for this release; Furness remains on V1.

What V2 adds

V2 binds a publish to the exact Create project and version, source and manifest hashes, destination identity, and idempotency key. Connect records a durable receipt so Create can reconcile a timeout without sending a second write.

• An identical retry returns the original destination result.
• Reusing the key for different content is rejected.
• A lost response is reconciled with the original key.
• Receipts preserve the exact package, version, artifact, and provenance.
• Disabling V2 stops new V2 writes while existing receipts remain readable.

These controls improve publishing safety and traceability. They do not change the SCORM runtime or promise a faster request.

Signed authorization and integrity

Create V2 is a product-to-product contract. An Allure Create service presents:

• a Connect API key with the internal-product scope;
• a short-lived portfolio authorization proof in X-Allure-Portfolio-Proof; and
• the same Idempotency-Key recorded in the publish request.

The portfolio proof is an RS256- or ES256-signed JWT. Connect selects the verification key by kid from the configured portfolio registry JWKS, validates the issuer and allure-connect audience, and binds the proof to the exact account, workspace, product link, action, and request hash. Signing-key rotation is handled through JWKS; an unknown cached key causes one fresh JWKS lookup and then fails closed. Customers do not mint this proof or exchange a shared signing secret.

Connect independently recomputes the canonical SHA-256 manifest hash and checks the source, content, project, version, and reporting provenance carried by the immutable learner manifest. A proof, request, or manifest that does not match those exact values is refused before packaging.

Receipts, reconciliation, and stable errors

Every accepted key resolves to one durable receipt. The receipt reports the current package/version identity, provenance, destination state, metering state, and whether the outcome is still unknown.

• Retry the same request with the same key after a transport failure.
• If the response was lost, read GET /api/v2/connect-packages/by-idempotency/{idempotencyKey} with a fresh portfolio proof.
• If the receipt says outcomeUnknown=true or remains reconciling, continue reconciliation. Do not publish through V1, invent a new key, or create a second destination version.
• Lookup and reconciliation remain available when new V2 acceptance is disabled, so rollback does not strand an existing eligible receipt. The Furness hard denial returns CREATE_PUBLISH_V2_DISABLED before proof or ledger access and therefore exposes no protected receipt state.

For a combined Create acceptance run, a destination is terminal only when the Create adapter reports status: "complete", the Connect receipt reports status: "completed" and connect.validationStatus: "valid", and packageId, packageVersionId, and artifactId are all non-empty. A 202, reconciling, or unknown outcome is lost-response evidence only; it must not seed TrainingOS or another downstream destination.

Errors use stable machine-readable codes. Important examples include IDEMPOTENCY_KEY_REUSED, MANIFEST_HASH_MISMATCH, PORTFOLIO_PROOF_REQUIRED, PORTFOLIO_PROOF_INVALID, PORTFOLIO_PROOF_UNAVAILABLE, CREATE_PUBLISH_NOT_FOUND, and CREATE_PUBLISH_V2_DISABLED. Authorization-dependent missing and unreadable receipts intentionally share the same not-found response so the lookup cannot be used to discover another workspace's records. The OpenAPI reference is the contract source for current status codes, headers, and response fields.

What does not change

• Existing V1 packages, versions, launch URLs, sessions, reports, and webhook history remain in place.
• Existing customers are not migrated automatically.
• V1 and V2 can operate in parallel for different workspaces.
• There is no announced V1 deprecation or removal date.
• A V2 rollout does not require customers to rotate their existing V1 API keys.

V2 will become the default for newly created Create workspaces only after the staged production ramp is accepted. Existing workspaces remain on their current path unless an owner approves a workspace-specific change.

Activation and rollback

Activation is allowlisted and destination-specific:

1. Connect enables its receiver for a non-customer canary workspace.
2. Create enables only the Connect destination for that same workspace.
3. Operators observe receipts, retries, authentication failures, latency, and destination errors.
4. The next destination is considered only after the observation window passes.

Rollback disables the Create destination and receiver write flags. It does not delete packages, versions, receipts, sessions, attempts, or audit history. Receipt lookup and reconciliation remain available so an unknown outcome is never retried through V1 or under a new key. An exact hosted stage bound before rollback may finish activation and begin its single meter; operators must reconcile accepted receipts rather than assuming the flag flip cancels them.

Optional migration for an existing workspace

Migration is optional and workspace-specific; there is no fleet-wide conversion or in-place rewrite of V1 records.

1. Keep every existing V1 package, launch URL, session, report, and webhook in service.
2. Select a new publish from an approved non-customer workspace. Do not use an existing V1 delivery as the canary.
3. Enable only the Connect receiver and that workspace's Create destination, then publish a new V2 version under a new idempotency key.
4. Observe authentication, receipt, reconciliation, latency, destination, and rollback signals through the approved window.
5. If the trial is accepted, use V2 for later publishes from that workspace. Existing V1 deliveries continue in parallel.
6. If the trial is stopped, disable new V2 writes and reconcile any accepted receipt. Do not delete or rewrite V1 or V2 history.

Furness/FidesAcademy is not eligible for this optional path while the server-side hard denial applies. Separate approval cannot override that denial; changing it would require a new reviewed release and exact workspace, package, operation, observation-window, and rollback authorization.

Existing customer protection

Customer workspaces are excluded from automatic activation. Furness/FidesAcademy remains on its existing V1 behavior and is explicitly excluded from V2 staging, canaries, and migration. Any future customer canary requires a separately reviewed workspace, package, operation, observation window, and rollback plan.

Related references

• Public V1 API reference
• Machine-readable OpenAPI
• API versioning policy
• SCORM API quick start