AIMS operator confirmations

POST /api/v1/aims/operator-confirmations issues a five-minute, one-time confirmation for an exact AIMS operator preview. It requires a workspace API key with current Admin or Owner workspace access and a current tenant-scoped AIMS assignment authorized for the requested capability. Personal keys and unauthenticated requests are rejected.

Send a unique Idempotency-Key header. It is always mandatory for this endpoint, independently of the global API v1 idempotency setting. Retrying the exact body with the same key returns the original response and sets Idempotency-Replayed: true; using that key with a different body returns 409 idempotency_replay_mismatch and never issues another confirmation.

Request

Run pnpm aims:operator ... without --apply and send the returned confirmationRequest as the JSON body. The schema is strict:

{
  "capabilityId": "aims.operator.backfill",
  "changeTicket": "CHG-1234",
  "target": {
    "organizationId": "org_1",
    "workspaceId": "ws_1",
    "ownerUserId": "user_1",
    "registrations": []
  }
}

expiresAt is optional and must be an offset ISO timestamp when the preview includes an operation expiry. Do not add actorId, organizationId, workspaceId, or authentication assurance at the top level. The endpoint derives identity, tenant and service_token assurance from the workspace key, validates the target scope, maps the capability to its AIMS action, and computes planHash server-side.

HTTP 201 returns the standard success envelope with data.confirmation and the AIMS assignment used to authorize issuance. Verify that data.confirmation.planHash equals the CLI preview before applying, then pass data.confirmation.id through the command's confirmation flag. A confirmation is consumed atomically and cannot be replayed.

Role grants

Role-grant previews return confirmationRequests.grantor and confirmationRequests.approver. Issue the grantor confirmation first with the grantor's workspace key. Issue the approver confirmation with a different user's key; the endpoint requires an unconsumed grantor confirmation for the same plan and rejects the same actor even when that actor holds both required roles.

The shared target includes beneficiaryRequiredAssurance. The endpoint derives both authenticated actor assurances as service_token, so the CLI preview must use --grantor-assurance service_token and --approver-assurance service_token. The grantor needs role_assignment.grant authority; the approver independently needs role_assignment.approve authority.

This endpoint cannot issue a matching confirmation for an mfa operator-assurance preview. MFA issuance requires a separate future surface that authenticates MFA rather than accepting it as a request claim.

Production manifest refresh

For an independent AIMS Reviewer or Manager using recent browser MFA, AI Governance offers Approve and enable. The preparer cannot make this decision. An eligible Organization Owner with a current System Owner assignment may do so alone only under explicit Owner authorization. For existing decisions use Workflows → Enable approved version. That action derives the manifest from the approved snapshot, rechecks current authority, activates governance and publishes the exact reviewed workflow. It does not require manually constructing these service-token confirmation requests. An authorization saved before a deployment failure is shown separately and can be retried without a new review. The browser never changes organization policy, clears a kill switch or replays failed events. The separate legacy service-token operator flow below remains available with its existing restrictions; it is not required to complete the two-person browser workflow. See AI governance for the UI walkthrough.

pnpm aims:operator refresh-manifest ... previews a production-only manifest creation or refresh. Its exact target binds the organization, workspace, immutable artifact snapshot, system version, workflow version, current assessment, authorized approval IDs, governed data-asset IDs and kill switch. Generate this body from the CLI preview; do not construct it manually.

The preview returns two bodies:

• confirmationRequests.creator uses aims.operator.refresh_manifest.creator and requires system.register authority.
• confirmationRequests.approver uses aims.operator.refresh_manifest.approver and independently requires system.approve authority.

Issue the creator confirmation first. In Independent review mode, the approver request must use a different workspace-key actor; the endpoint requires an unconsumed creator confirmation with the same canonical plan hash and rejects one identity attempting both sides. The underlying manifest service also enforces independence from the system creator, system-version creator and referenced approval actors. Both authenticated assurances are derived as service_token. With explicit Owner authorization enabled, an Organization Owner with a current System Owner service-token assignment may request both confirmations using their own workspace key. These remain two separate, single-use confirmations for the exact plan. Both issuance and manifest creation check current scoped authority; passing identical actor IDs in a preview does not grant permission. The manifest hashes the Owner, assignment and policy revision. Disabling the policy invalidates owner approvals and owner-authorized manifests without deleting their evidence. The same exception permits the Owner to grant and approve a delegated role, but never a role whose beneficiary is themselves. Pass the returned IDs as --creator-confirmation-id and --approver-confirmation-id with --apply true. The CLI fixes the environment to production and rejects distinct confirmation IDs that do not match the confirmed plan.

Errors

• 401: missing or invalid bearer key.
• 400: missing or invalid Idempotency-Key.
• 403: personal/non-workspace key, insufficient workspace authority, missing AIMS assignment, cross-tenant target, or separation-of-duties failure.
• 404: the authenticated key's workspace no longer exists.
• 409: idempotency key reused for a different plan, a request already in progress, or an issuance outcome requiring reconciliation.
• 422: malformed or extra request fields.
• 500: confirmation persistence failed.

If an ordinary operator mutation fails after consuming a confirmation, issuance remains fail closed. Create a fresh preview and request new confirmation IDs; do not retry consumed IDs. Backfill is the transactional exception: confirmation consumption and all registrations roll back together, so the same approved plan can be retried after correcting a deterministic failure.