# rotateAgentChannelKey mutation · in the family [System and integration setup](/reference/system-and-integration-setup/) ## What it does Mint a fresh signing key for the channel — the outgoing key keeps verifying for seven more days, then retires. Rotate the signing key of an AgentChannel: the engine mints a FRESH ES256 keypair — the new public JWK joins the record's signingKeys as the current key, the outgoing key gains retiresAt = now + 7 days (the spec's grace — platforms keep verifying with it until then), keys already past their retiresAt are pruned, and the private halves rewrite the AGKEY credential row (never on the wire: nothing to paste). Allowed in every live state (draft · live · paused); a doomed channel refuses CONFLICT/IMMUTABLE. OCC by revision (CONFLICT/REVISION_STALE). Requires the unrestricted capability (the class). ## What happens Platforms re-read the public keys from the profile; nothing to paste anywhere — the private half never leaves the engine. ## Who may call it Capability area: **System and integration setup** — Registers, connections and the settings your systems run on. - Owner - System Administrator - An API key whose scope allows `api:rotateAgentChannelKey` ## Arguments | Name | Type | Required | Notes | | --- | --- | --- | --- | | `id` | [ID](/types/#scalars) `ID!` | yes | The id of the record. | | `revision` | [ID](/types/#scalars) `ID!` | yes | The revision id you read on the record; the change is refused if an edit landed in the meantime. | | `reason` | [String](/types/#scalars) | no | No further notes. | ## Returns [AgentChannel](/types/AgentChannel/) `AgentChannel!` — An AgentChannel — the merchant’s CONTROLS over the agentic-commerce channel: exactly ONE record per Organization that says WHAT an AI shopping agent may sell over the open Universal Commerce Protocol and HOW — the selling location (prices · stock · tax origin), the listed Collections (EMPTY = nothing listed), an optional agent price plane (a PriceList), discount codes on/off, a checkout cap, the fulfillment methods + flat-rate shipping cards + ship-to countries + pickup locations, the buyer facts required, the pre-approved agent platforms (EMPTY = every platform refused), the buyer-consent defaults, the return/warranty policy texts, the checkout session TTL, and the engine-minted ES256 signing keys (the PUBLIC halves — the private halves live in the credential store, never on the wire). Lifecycle draft → live → paused → live | doomed: publish and resume run the completeness rule record-aware (the channel must be able to sell); pause withholds the channel (agents read unavailable + Retry-After); a LIVE channel never dooms in one step (pause first); doom releases the one-per-org marker so the organization may start over. The protocol doors (the profile, the catalog, the checkout — onward) READ this record; the adapter adds no business rule of its own. Payment handlers are NEVER typed here — the profile derives them from the organization’s connected-account facts. ## Example request ```graphql mutation ExampleRotateAgentChannelKey($id: ID!, $revision: ID!, $reason: String) { rotateAgentChannelKey(id: $id, revision: $revision, reason: $reason) { id sysId type caption status parentId rootId createdAt updatedAt revisionNum revision logicalFacilityId pickupLogicalFacilityIds shipToCountries collectionIds divisionId showStockLevels excludedVariantIds priceListId allowDiscountCodes maxCheckoutTotalMinor fulfillmentMethods handlingDays requireBuyerEmail requireBuyerPhone rateClass returnPolicy warrantyPolicy checkoutTtlMinutes identityLinking requireLinkedBuyer } } ``` Variables: ```json { "id": "01900000-0000-7000-8000-37386ae00000", "revision": "01900000-0000-7000-8000-b7960e180000", "reason": "Correcting a miscount." } ``` Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`. ## Example response ```json { "data": { "rotateAgentChannelKey": { "id": "01900000-0000-7000-8000-37386ae00000", "sysId": "AG-EXMP-0000-000F", "type": "AgentChannel", "caption": "Blue jeans", "status": "draft", "parentId": "01900000-0000-7000-8000-065235280000", "rootId": "01900000-0000-7000-8000-a093dd800000", "createdAt": "2027-01-31T00:00:00.000Z", "updatedAt": "2027-01-31T00:00:00.000Z", "revisionNum": 1, "revision": "01900000-0000-7000-8000-b7960e180000", "logicalFacilityId": "01900000-0000-7000-8000-8026f71c0000", "pickupLogicalFacilityIds": [ "01900000-0000-7000-8000-095d4a1d0000" ], "shipToCountries": [ "" ], "collectionIds": [ "01900000-0000-7000-8000-b1c179550000" ], "divisionId": "01900000-0000-7000-8000-25bd925b0000", "showStockLevels": true, "excludedVariantIds": [ "01900000-0000-7000-8000-6ad77b420000" ], "priceListId": "01900000-0000-7000-8000-7844e9fb0000", "allowDiscountCodes": true, "maxCheckoutTotalMinor": 1, "fulfillmentMethods": [ "ship" ], "handlingDays": 1, "requireBuyerEmail": true, "requireBuyerPhone": true, "rateClass": "low", "returnPolicy": "", "warrantyPolicy": "", "checkoutTtlMinutes": 1, "identityLinking": true, "requireLinkedBuyer": true } }, "extensions": { "at": { "callId": "01EXAMPLE-CALL-ID", "version": { "requested": { "name": "genesis", "number": 0 }, "serviced": { "name": "genesis", "number": 0 } } } } } ``` ## Errors this call can answer - `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/)) - `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/)) - `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/)) - `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/)) - `NOT_FOUND/*` — That record could not be found. ([NOT_FOUND](/errors/NOT_FOUND/)) - `CONFLICT/*` — The record’s state, or a change made in the meantime, does not allow this; the codes are on the CONFLICT page. ([CONFLICT](/errors/CONFLICT/)) - `VALIDATION/VERSION_REQUIRED` — The request did not say which app version it came from. ([VALIDATION](/errors/VALIDATION/)) ## Used in - [Let AI shopping agents buy from you](/use-cases/sell-through-shopping-agents/)