DOCUMENTATIONv2

POST

Developer access

Revoke request signing key

/api/v2/security/signing-keys/{key_id}/revocations

AUTHENTICATIONBearer token · security:writeAUTHORITATIVE OWNERdeveloper-platformCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

Revoke an active request-signing key after purpose-bound step-up authorization.

WHEN THIS CALL IS USEFUL

Call this with a fresh purpose-bound step-up grant when a request-signing key is compromised, retired, superseded, or no longer permitted to authorize signed requests.

OUTCOME · Create or advance

What changes

Creates or advances only the request-signing key resource described by this contract after authorization, validation, policy, and idempotency gates pass.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance request-signing key.
Gives human and agentic integrations one discoverable path from service identity and reference data to executable OpenAPI, capability ownership, guides, SDK status, and request-signing controls.

ISOLATION + AUTHORITY

Public service metadata, the OpenAPI document, the capability registry, guides, SDK listings, bearer credentials, step-up grants, and request-signing keys are separate artifacts. Discovery metadata grants no tenant, wallet, custody, payment, settlement, publisher, matching, or trading authority; public signing-key metadata never includes private key material.

BEFORE YOU CALL

Authenticate at the documented boundary: bearer+scope.
Supply the required key_id (path), step_up_token (body) exactly as defined by the live contract.
Resolve whether the caller needs public discovery, bearer authorization, purpose-bound step-up, or RFC 9421 request signing; do not substitute one mechanism for another.

WHAT TO DO NEXT

Re-read the signing-key inventory or target key and confirm the resulting lifecycle state before sending another sensitive request.
After an ambiguous response, reconcile state before retrying; a step-up grant remains bound to its declared purpose and expiry.

AGENT GUIDANCE

Use request-signing key only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required key_id (path), step_up_token (body) exactly as defined by the live contract.
Treat deployment identity, OpenAPI schema, capability readiness, guide narrative, SDK publication, bearer authorization, step-up authorization, and request-signing proof as distinct inputs; none substitutes for another.
After a timeout or conflict, read authoritative state before deciding whether an equivalent retry is safe.

MACHINE CONTRACT

The exact deployed parameters, schemas, responses, security requirements, and Hybrid-Chain agent metadata are authoritative at this operation's production OpenAPI JSON Pointer. The readable tables below add integration guidance; the deployed OpenAPI controls if guidance and the machine contract ever differ.

Open the authoritative production contract ↗

EXTENDED INTEGRATION GUIDANCE

Readable request and response reference

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

Bearer tokenCredential containing the security:write scope.EXAMPLEBearer hc_live_…

key_idpathRequired

hck_ identifierActive signing key to revoke.

step_up_tokenbodyRequired

hcsu_ purpose-bound tokenFresh API_SIGNING_KEY_REVOCATION authorization.

REQUEST

JSON body example

{
  "step_up_token": "hcsu_…"
}

STABLE ERROR CODES

Branch on the code, then follow the recovery action

These codes are published by the authoritative gateway contract for this endpoint. Treat message as safe diagnostic text; integrations should branch on code and HTTP status.

STATUSCODEMEANING

400invalid_jsonThe JSON body is malformed or fails the published identity-security schema.

400invalid_security_requestThe session, scope, public key, proof, or purpose-bound security request is invalid.

401invalid_credentialsThe bearer, client assertion, or proof-of-possession credential is invalid.

403step_up_requiredFresh purpose-bound authenticator verification or stronger authority is required.

404signing_key_not_foundThe requested signing-key or workload-client resource was not found.

409security_conflictThe requested identity-security transition conflicts with current state.

503identity_security_unavailableThe authoritative Identity security service is temporarily unavailable.

RESPONSES

Status and payload examples

200Signing key revoked immediately.Mutation completed · JSON RESPONSE+

{
  "key_id": "hck_…",
  "status": "REVOKED"
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then re-read the signing-key inventory or target key and confirm the resulting lifecycle state before sending another sensitive request.
RETRY SAFETY: Do not repeat a successful mutation merely to confirm it. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Persist returned identifiers, versions, commitments, and receipts. Refresh the application, credential or callback record; compare scope, key identifier, secret-display state, version, and revocation or rotation receipt.

400The request shape is invalid.Request must change · JSON RESPONSE+

{
  "code": "invalid_security_request",
  "message": "The request shape is invalid."
}

INTEGRATION DECISIONinvalid_security_request

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Refresh the application, credential or callback record; compare scope, key identifier, secret-display state, version, and revocation or rotation receipt.
ESCALATE WHEN: Escalate when a secret-bearing result was lost, key or callback state is ambiguous, or least-privilege scope cannot be established.

401The bearer credential is invalid.Authentication required · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "The bearer credential is invalid."
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Discard the rejected credential, complete the documented authentication or reassertion flow, and rebuild any request signature with fresh timestamps and nonces.
RETRY SAFETY: Retry only with a newly valid credential and fresh replay-protection values. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Assume the outcome is unknown only when the connection failed after transmission; otherwise authentication failed before domain work. Refresh the application, credential or callback record; compare scope, key identifier, secret-display state, version, and revocation or rotation receipt.
ESCALATE WHEN: Escalate when a secret-bearing result was lost, key or callback state is ambiguous, or least-privilege scope cannot be established.

403A matching fresh step-up authorization is required.Authority or policy denied · JSON RESPONSE+

{
  "code": "step_up_required",
  "message": "A matching fresh step-up authorization is required."
}

INTEGRATION DECISIONstep_up_required

CALLER ACTION: Verify the exact scope, tenant or workspace membership, owner boundary, step-up purpose, feature policy, and resource eligibility. Never broaden authority automatically.
RETRY SAFETY: Do not retry until the missing authority or policy condition has been deliberately resolved with least privilege.
STATE RECONCILIATION: Confirm the caller and resource resolve to the same authority boundary for developer applications, credentials, signing keys, callbacks, scopes, secrets, and lifecycle receipts.
ESCALATE WHEN: Escalate when a secret-bearing result was lost, key or callback state is ambiguous, or least-privilege scope cannot be established.

404The active key does not exist for this identity and client.Resource not visible · JSON RESPONSE+

{
  "code": "signing_key_not_found",
  "message": "The active key does not exist for this identity and client."
}

INTEGRATION DECISIONsigning_key_not_found

CALLER ACTION: Verify the canonical identifier and authenticated owner boundary. A 404 may intentionally conceal a resource outside the caller's authority.
RETRY SAFETY: Do not retry the unchanged identifier repeatedly. Refresh the relevant collection or lookup before choosing another identifier.
STATE RECONCILIATION: Refresh the application, credential or callback record; compare scope, key identifier, secret-display state, version, and revocation or rotation receipt.
ESCALATE WHEN: Escalate when a secret-bearing result was lost, key or callback state is ambiguous, or least-privilege scope cannot be established.

503Identity security is unavailable.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "identity_security_unavailable",
  "message": "Identity security is unavailable."
}

INTEGRATION DECISIONidentity_security_unavailable

CALLER ACTION: Preserve the exact request and treat the outcome as uncertain until authoritative state proves whether it committed.
RETRY SAFETY: Reconcile before retrying. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt. Use bounded backoff with jitter.
STATE RECONCILIATION: Refresh the application, credential or callback record; compare scope, key identifier, secret-display state, version, and revocation or rotation receipt.
ESCALATE WHEN: Escalate when a secret-bearing result was lost, key or callback state is ambiguous, or least-privilege scope cannot be established.

OPERATIONAL NOTES

Security and lifecycle guarantees

The request accepts only step_up_token; no reason field is part of the executable contract.
A revoked key cannot authorize a new signed request; previously accepted operations retain their audit evidence.

DOCUMENTATION STATUS

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-09-11T06:35:11.572Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation ↗Return to the V2 directory ↗