DOCUMENTATIONv2

POST

Authentication

Create session

/api/v2/auth/sessions

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

PURPOSE + BUSINESS CONTEXT

Verify existing Hybrid credentials and issue short-lived V2 access plus a rotating refresh credential.

WHEN THIS CALL IS USEFUL

Call this when an existing account needs a new bounded client session after credential verification, device identification, and any required authenticator challenge.

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

No bearer credential is required; apply bounded filters and canonical public identifiers where the contract provides them.
Supply the required email (body), password (body), device_id (body), platform (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

Protect the access and rotating refresh credentials according to the client platform, and never expose them in URLs, logs, or analytics.
Use the session's expiry and rotation contract for renewal, and revoke the session when the device or client is no longer trusted.

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 email (body), password (body), device_id (body), platform (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

emailbodyRequired

email address · max 254Existing Hybrid-Chain account email.

passwordbodyRequired

string · max 512Account password; used only to calculate the legacy seed-bound proof and never logged or retained.

two_factor_codebodyOptional

6-digit TOTPRequired when the account has an authenticator enabled.

device_idbodyRequired

safe identifier · 16–128Stable identifier scoped to this application installation.

device_namebodyOptional

string · max 160Human-readable client label.

platformbodyRequired

ios | android | web | serverClient class for session inventory and policy.

device_public_key_spkibodyOptional

SPKI stringOptional device key for future phishing-resistant capabilities.

REQUEST

JSON body example

{
  "email": "[email protected]",
  "password": "correct horse battery staple",
  "two_factor_code": "123456",
  "device_id": "web-client-7f4c2109",
  "device_name": "Firefox on macOS",
  "platform": "web"
}

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

200Short-lived access token and single-use rotating refresh token.Mutation completed · JSON RESPONSE+

{
  "data": {
    "access_token": "hcm_…",
    "refresh_token": "hcmr_…",
    "token_type": "Bearer",
    "expires_in": 900,
    "refresh_expires_in": 2592000,
    "client_id": "client-01",
    "session_id": "9b51ed4c9c8f4aec85d1bd5520e40557",
    "scopes": [
      "profile:read",
      "contracts:read"
    ]
  }
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then protect the access and rotating refresh credentials according to the client platform, and never expose them in URLs, logs, or analytics.
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 request fields are invalid.Request must change · JSON RESPONSE+

{
  "code": "invalid_authentication_request",
  "message": "The request fields are invalid."
}

INTEGRATION DECISIONinvalid_authentication_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 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 credentials could not be verified.Authentication required · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "The credentials could not be verified."
}

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

409An authenticator code is required.State reconciliation required · JSON RESPONSE+

{
  "code": "two_factor_required",
  "message": "An authenticator code is required."
}

INTEGRATION DECISIONtwo_factor_required

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

503Authentication is temporarily unavailable.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "authentication_unavailable",
  "message": "Authentication is temporarily unavailable."
}

INTEGRATION DECISIONauthentication_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 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

The gateway derives client_id by loading the profile with the authenticated upstream token; callers cannot choose the identity receiving the V2 session.
Access tokens expire after 15 minutes. Refresh credentials rotate atomically and are invalid after one successful use.

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/auth/loginAUTH: Log a User in

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 ↗