DOCUMENTATIONv2

POST

Authentication

Revoke session

/api/v2/auth/sessions/{session_id}/revocations

AUTHENTICATIONBearer token · sessions:writeAUTHORITATIVE OWNERidentity-access · identity-serviceCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

Revoke the current session or use fresh step-up authorization to revoke another client session.

WHEN THIS CALL IS USEFUL

Call this to end the current session or, with the required fresh step-up authorization, revoke another identified client session during device removal or incident response.

OUTCOME · Create or advance

What changes

Creates or advances only the session 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 session.
Makes credential and account-lifecycle transitions explicit while keeping passwords, authenticator secrets, recovery codes, refresh tokens, devices, sessions, and account state under separate controls.

ISOLATION + AUTHORITY

Tenant identity, profile, password, authenticator enrollment, recovery code, device, session, access token, refresh credential, step-up grant, and account-closure state remain distinct. Authentication proves only the admitted session and scopes; it grants no workspace role, wallet, payment, settlement, publisher, matching, or trading authority.

BEFORE YOU CALL

Authenticate at the documented boundary: bearer+scope.
Supply the required session_id (path), session_id (body) exactly as defined by the live contract.
Resolve the tenant, account lifecycle, client device, credential state, authenticator or recovery basis, and required step-up purpose for this security transition.

WHAT TO DO NEXT

Refresh the session inventory and confirm the target session is revoked before considering the security action complete.
If the response was ambiguous, reconcile by session identifier before attempting another revocation or issuing replacement credentials.

AGENT GUIDANCE

Use session only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required session_id (path), session_id (body) exactly as defined by the live contract.
Keep registration, activation, credential verification, session issuance, refresh rotation, authenticator enrollment, confirmation, recovery, revocation, and account closure as separate lifecycle transitions.
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 sessions:write scope.EXAMPLEBearer hc_live_…

session_idpathRequired

32-character session UUIDSession to revoke.

session_idbodyRequired

32-character session UUIDMust exactly match the path value.

step_up_tokenbodyOptional

hcsu_ purpose-bound tokenRequired when revoking any session other than the current one.

REQUEST

JSON body example

{
  "session_id": "9b51ed4c9c8f4aec85d1bd5520e40557",
  "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

200Session and its dependent push/messaging credentials revoked.Mutation completed · JSON RESPONSE+

{
  "data": {
    "revoked": true,
    "session_id": "9b51ed4c9c8f4aec85d1bd5520e40557"
  }
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then refresh the session inventory and confirm the target session is revoked before considering the security action complete.
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 relevant account, session, authenticator, client, key, or one-time transaction state; replace consumed or expired credentials instead of replaying them.

400The path and body session identifiers differ.Request must change · JSON RESPONSE+

{
  "code": "session_id_mismatch",
  "message": "The path and body session identifiers differ."
}

INTEGRATION DECISIONsession_id_mismatch

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 relevant account, session, authenticator, client, key, or one-time transaction state; replace consumed or expired credentials instead of replaying them.
ESCALATE WHEN: Escalate when account or tenant binding, session revocation, authenticator state, key rotation, or one-time-token consumption cannot be reconciled securely.

401The access token is invalid.Authentication required · JSON RESPONSE+

{
  "code": "invalid_session_credential",
  "message": "The access token is invalid."
}

INTEGRATION DECISIONinvalid_session_credential

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 relevant account, session, authenticator, client, key, or one-time transaction state; replace consumed or expired credentials instead of replaying them.
ESCALATE WHEN: Escalate when account or tenant binding, session revocation, authenticator state, key rotation, or one-time-token consumption cannot be reconciled securely.

403Fresh SESSION_REVOCATION step-up is required.Authority or policy denied · JSON RESPONSE+

{
  "code": "session_action_forbidden",
  "message": "Fresh SESSION_REVOCATION step-up is required."
}

INTEGRATION DECISIONsession_action_forbidden

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 accounts, activations, sessions, authenticators, step-up grants, workload identities, keys, and revocations.
ESCALATE WHEN: Escalate when account or tenant binding, session revocation, authenticator state, key rotation, or one-time-token consumption cannot be reconciled securely.

404The session does not exist for this identity.Resource not visible · JSON RESPONSE+

{
  "code": "session_not_found",
  "message": "The session does not exist for this identity."
}

INTEGRATION DECISIONsession_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 relevant account, session, authenticator, client, key, or one-time transaction state; replace consumed or expired credentials instead of replaying them.
ESCALATE WHEN: Escalate when account or tenant binding, session revocation, authenticator state, key rotation, or one-time-token consumption cannot be reconciled securely.

OPERATIONAL NOTES

Security and lifecycle guarantees

Revoking the current session requires no extra step-up. Revoking another client consumes a five-minute SESSION_REVOCATION authorization.

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.

GET/api/v1/auth/logoutAUTH: Log a User out

POST/api/v1/sessions/destroySESSION: Destroy Session

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 ↗