POST /validate

Start in Observe on one route. Use the deployment URL and installed package version supplied for your workspace. Historical host examples and source capabilities do not establish a live service or published release.

Endpoint

POST https://gate.x-lock.dev/validate

SDK clients default to MANDATE_GATE_URL (or production) and call {gateUrl}/validate.

Description

Validates a MANDATE token server-to-server when a route needs stateful replay and session-continuity checks. The response is decision-oriented (success, action, optional refresh metadata). Raw risk scores are never returned.

This is not a browser API. Anonymous callers cannot use it.

When to use /validate vs other modes

Node helpers: validateHosted / validateHostedRequest, mandateHosted (Express),

withMandateHosted (Next.js). With MANDATE_LIVE_MUTATING (default on in

production/staging), ordinary middleware can route POST/PUT/PATCH/DELETE

through this endpoint automatically when an API key is configured.

Request

Content-Type: application/json

Authorization: Bearer mak_... with tokens:validate scope

{
  "token": "<opaque-base64url-token-from-X-Mndt>",
  "secret": "mss_live_...",
  "site_key": "sk_live_...",
  "high_value": true,
  "min_score": 0.6,
  "path": "/api/checkout",
  "endpoint_value": "payment",
  "request_proof": "v1.<timestamp>.<nonce>.<sig>",
  "request_method": "POST",
  "account_key": "customer-scoped-account-or-email-hash"
}

Token values are opaque (encrypted/signed binary, base64url-encoded). They

are not JWTs and do not use a stable mndt_v1_ prefix — treat the sample as a

placeholder only.

Optional route and browser context

Optional route fields such as path, endpoint, route, and endpoint_value

help MANDATE classify checks and issue route-scoped refreshed tokens.

For browser-originated high-value requests, forward the runtime's X-Mndt-Req

header as request_proof and the original protected method as request_method.

Sessions with a bound request-proof key fail closed when that proof is missing

or does not match the protected request.

Optional browser-context hints such as origin, site_origin, client_ip /

ip, asn, and country are not trusted continuity inputs by default. The

gate derives continuity from the connection and live session state unless

body-continuity trust is explicitly enabled and the request arrives through a

trusted proxy peer.

account_key is optional pressure context for routes such as login, signup, and

account recovery. Use a stable customer-side account identifier or hash; MANDATE

HMACs it with site signing material before aggregate pressure detection.

queue_token is only returned by MANDATE queue escalation and is validated

server-side on retry. Do not create queue tokens in browser code.

Observe vs enforce (escalation)

New site keys are seeded with observe-mode posture for common login, signup,

session, checkout, cart, reserve, and public routes. In observe mode, hosted

validation records pressure and recommended escalation but does not return

throttle, queue, or step-up responses. Those actions require **Shape high-risk

traffic** in Policies or config.escalation.mode: "enforce" via the API.

Monthly request limit

Reaching the workspace's monthly request allowance never refuses its

visitors. Until the next period starts or the plan is upgraded, protection is

observe-only: hosted validation keeps verifying proof and recording decisions,

escalation, rate-limit rules and Network Intelligence run as in observe mode,

and detection verdicts are recorded but not enforced. Responses then include

"planLimitObserveOnly": true, plus "planLimitObserved" listing each

verdict that was recorded but not enforced. Treat these entries as diagnostic

metadata, not stable identifiers to branch on. Protocol-integrity failures

are still refused as usual: invalid, expired or replayed tokens and proofs,

wrong origin or site key, broken session continuity or bindings, and

contained solver sessions. Plan limits are not enforced during the public

beta.

One-shot consumption and high-value continuity

Hosted validation consumes authenticated proof once and cross-references the decision against

live server-side state. Reused, stale, or mismatched proof fails closed with a customer-safe

unsuccessful response; the specific failed check is not part of the public contract.

Response

Content-Type: application/json

Hosted responses intentionally omit raw scores. Official SDKs surface

score: null for hosted results. Branch on success and action only.

Success (200)

{
  "success": true,
  "human": true,
  "sessionId": "sess_a1b2c3d4e5",
  "action": "allow",
  "expiresAt": 1781605500,
  "token": "<optional-refreshed-opaque-token>",
  "routeClass": "high",
  "tokenTtlSeconds": 60,
  "tokenMarker": "e"
}

Escalation (202 / 401 / 403 / 429)

{
  "success": false,
  "action": "queue",
  "siteKey": "sk_live_...",
  "sessionId": "sess_a1b2c3d4e5",
  "routeClass": "high",
  "reason": "inventory_pressure",
  "queueToken": "qtok_...",
  "retryAfterSeconds": 12
}

For step_up responses, MANDATE includes recommendedStepUp plus a

stepUpAttemptId. After your customer-owned MFA, passkey, email,

payment-verification, support-review, or custom-webhook flow finishes, report

the terminal outcome with:

POST /api/v1/step-up-attempts/{stepUpAttemptId}
Authorization: Bearer mak_live_...
Content-Type: application/json

{"status":"completed"}

status must be completed, failed, or bypassed. The API key must carry

the tokens:validate scope. The endpoint is aggregate-only and rejects unknown

request fields; do not send user identity proof data, raw tokens, sessions,

account identifiers, request bodies, or collector payloads.

Error (400 / 401 / 403 / 422 / 503)

{
  "success": false,
  "message": "Verification was not successful."
}

Public failure handling is intentionally coarse:

See Errors and recovery. Detailed verification reasons and their mapping to public

responses are not part of the public API contract.

Rate limiting

This endpoint is rate limited after API-key authorization.

Keep hosted authority for protected browser actions at high request volume.

Plan route capacity and use the supported adapters; a first-party cookie is a

transport credential, not an instruction to replace live verification with

local crypto. Rate-limit replies must not trigger automatic business replay.

Do not “scale” by re-enabling offline X-Mndt local crypto in production.

That path is fail-closed by default because harvested tokens can be accepted

until TTL without the gate observing the protected action.