DOCUMENTATIONv2

POST

Identity sessions and federation

Exchange workload assertion

/api/v2/auth/workload-token-exchanges

AUTHENTICATIONNone · publicAUTHORITATIVE OWNERidentity-serviceCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

Verify a one-time Ed25519 private-key JWT assertion and issue a refreshless, network-bound scoped workload bearer with a 15-minute default and network-specific lifetime cap.

WHEN THIS CALL IS USEFUL

Use when an enrolled machine or agent needs a short-lived refreshless bearer for an explicit scope subset and network.

OUTCOME · Create or advance

What changes

Atomically consumes the assertion jti and issues an opaque workspace- and network-bound bearer. No refresh token or client secret is issued.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance workload assertion.
Separates subject identity, consent, evidence, provider output, review, issuer credentials, and relying-party acceptance instead of collapsing them into a universal trust score.

ISOLATION + AUTHORITY

Bearer subject, tenant, purpose, policy version, role, issuer, reviewer, provider, and relying-party boundaries remain distinct. The response or transition grants no payment, custody, settlement, publisher, matching, or trading authority and must not expose regulated evidence beyond the live schema.

BEFORE YOU CALL

No bearer credential is required; apply bounded filters and canonical public identifiers where the contract provides them.
Supply the required grant_type (body), client_assertion_type (body), client_assertion (body), network_id (body) exactly as defined by the live contract.
Resolve the applicable purpose, policy version, consent or role basis, and required assurance before relying on this result.

WHAT TO DO NEXT

Re-read workload assertion using the canonical identifier returned by this operation.
Reconcile an ambiguous response with the same idempotency key before attempting another mutation.
Use the returned lifecycle state and policy version to choose the next least-privilege trust action; do not infer a missing stage.

AGENT GUIDANCE

Use workload assertion only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required grant_type (body), client_assertion_type (body), client_assertion (body), network_id (body) exactly as defined by the live contract.
Treat policy availability, consent, evidence capture, completed checks, review, decision, credential issuance, validity, and relying-party acceptance as separate facts.
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

grant_typebodyRequired

client_credentialsOAuth client-credentials grant.

client_assertion_typebodyRequired

urn:ietf:params:oauth:client-assertion-type:jwt-bearerPrivate-key JWT client authentication profile.

client_assertionbodyRequired

EdDSA compact JWTSingle-use assertion with iss=sub=client_id, exact audience, signed network_id, iat, exp within five minutes, and unique jti.

scopebodyOptional

space-separated scopesOptional subset of the client allowed scopes. Omit it to request the full allowed set.

network_idbodyRequired

hybrid-devnet | hybrid-testnet | hybrid-mainnetMust exactly match the signed assertion and target operational wallet context.

expires_inbodyOptional

integer · 60–14400Requested bearer lifetime. Defaults to 900 seconds and is capped by network policy.

REQUEST

JSON body example

{
  "grant_type": "client_credentials",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "client_assertion": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.…",
  "scope": "wallet",
  "network_id": "hybrid-testnet",
  "expires_in": 900
}

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

200Refreshless, network-bound workload bearer; 15-minute default.Mutation completed · JSON RESPONSE+

{
  "access_token": "hcw_…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "wallet",
  "client_id": "hcwc_…",
  "workspace_id": "b00dc220da8f480d86cdc11341372746",
  "network_id": "hybrid-testnet",
  "renewal_mode": "REASSERT"
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then re-read workload assertion using the canonical identifier returned by this operation.
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. Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.

400The grant or assertion shape is unsupported.Request must change · JSON RESPONSE+

{
  "code": "invalid_security_request",
  "message": "The grant or assertion shape is unsupported."
}

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. Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

401The assertion is invalid, expired, replayed, network-mismatched, or requests unauthorized scopes.Authentication required · JSON RESPONSE+

{
  "code": "invalid_client_assertion",
  "message": "The assertion is invalid, expired, replayed, network-mismatched, or requests unauthorized scopes."
}

INTEGRATION DECISIONinvalid_client_assertion

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. Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

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

{
  "code": "identity_security_unavailable",
  "message": "Identity workload authentication 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: Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

OPERATIONAL NOTES

Security and lifecycle guarantees

The workload private key never leaves the client. Hybrid-Chain stores only the public Ed25519 key and issues no client secret or refresh token.
When the bearer expires, sign a new single-use assertion and exchange it again; long-running agents reassert without a human login.
The default is 900 seconds. Maximum lifetimes are 3600 seconds on Mainnet, 7200 on Testnet, and 14400 on Devnet.
The assertion, request, token, AI assignment, operational wallet, workspace, and network must agree; mismatches fail closed.

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 ↗