DOCUMENTATIONv2

POST

Session Management

Register request signing key

/api/v2/security/signing-keys

AUTHENTICATIONBearer token · security:writeAUTHORITATIVE OWNERdeveloper-platform · identity-accessCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

Register an Ed25519 public JWK after proof of possession and purpose-bound step-up authorization.

WHEN THIS CALL IS USEFUL

Call this after generating an Ed25519 key pair, retaining the private key outside Hybrid-Chain, proving possession of the public JWK, and obtaining a fresh step-up grant for key registration.

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 public_key_jwk (body), proof (body), 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 public_key_jwk (body), proof (body), 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_…

public_key_jwkbodyRequired

OKP Ed25519 public JWKPublic key with kty=OKP, crv=Ed25519, and a 32-byte unpadded base64url x value.

proofbodyRequired

unpadded base64url Ed25519 signatureProof over the domain-separated canonical registration statement.

step_up_tokenbodyRequired

hcsu_ purpose-bound tokenFresh API_SIGNING_KEY_REGISTRATION authorization.

labelbodyOptional

string · max 160Human-readable device or machine label; defaults to API signing key.

rotated_from_key_idbodyOptional

hck_ identifierExisting key being replaced; it must belong to this identity and client.

REQUEST

JSON body example

{
  "public_key_jwk": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "…"
  },
  "proof": "…",
  "step_up_token": "hcsu_…",
  "label": "Production settlement worker",
  "rotated_from_key_id": null
}

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

201Server-assigned public signing key registered after proof of possession.Mutation completed · JSON RESPONSE+

{
  "key_id": "hck_…",
  "algorithm": "ed25519",
  "thumbprint": "f4a5…",
  "label": "Production settlement worker",
  "status": "ACTIVE",
  "rotated_from_key_id": null,
  "created_at": null,
  "expires_at": null,
  "revoked_at": null
}

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 JWK or proof of possession is invalid.Request must change · JSON RESPONSE+

{
  "code": "invalid_request",
  "message": "The JWK or proof of possession is invalid."
}

INTEGRATION DECISIONinvalid_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.

409The public key is already registered or the selected predecessor is invalid.State reconciliation required · JSON RESPONSE+

{
  "code": "signing_key_conflict",
  "message": "The public key is already registered or the selected predecessor is invalid."
}

INTEGRATION DECISIONsigning_key_conflict

CALLER ACTION: Stop the mutation sequence and fetch the latest authoritative resource, lifecycle state, version, ETag, reservation, or existing idempotency result.
RETRY SAFETY: Retry only after reconciling the conflict. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
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

Sign key-sorted compact JSON containing algorithm=ed25519, the authenticated client_id, label, public_key_jwk, and rotated_from_key_id, prefixed by hybrid-chain/api-signing-key-registration/v1 plus a NUL byte.
Hybrid-Chain assigns key_id after verifying possession; clients do not submit a key identifier.
Sensitive V2 mutations subsequently require the bearer plus an RFC 9421 Ed25519 HTTP Message Signature and RFC 9530 Content-Digest.

UPGRADING FROM V1

Legacy calls replaced by this operation

If you maintain an older integration, use this map to find the V2 replacement. Do not translate the old request field-for-field: rebuild it from the V2 parameters and schemas above because identity, authorization, replay protection, and response semantics may have changed.

POST/api/v1/sessions/newSESSION: Create new API Key

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 ↗