Report the result of your own step-up check for a held decision

POST /api/v1/decisions/{decisionId}/step-up · operationId reportStepUp

For developers: your server sends this request with a server key; it is not a button in the dashboard. To see the same information without code, open Control › Approvals › Waiting in the dashboard.

For a decision held for review (review), your backend may run its own check (passkey or MFA re-auth, Turnstile, its own approval) instead of waiting for the hosted queue. Checked like an approval: same Site, session, action and target, still waiting, within 15 minutes. passed approves and uses the hold at once (proceed true, one time; the same report within 60 s is answered again with replayed true); failed rejects it. Either way review.resolved is sent with via step-up. A pass is evidence, not authorization. Refusals are 409 step_up_not_held, step_up_mismatch, step_up_settled or step_up_expired.

Authentication

Send Authorization: Bearer YOUR_SERVER_KEY (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

Parameters

decisionId (path, string, required)

Request body

Content-Type: application/json (required)

sessionToken (string, required) · minLength 1, maxLength 250: Opaque browser session token; do not log.
actionId (string, required) · pattern ^[A-Za-z0-9_-]{1,64}$
targetId (string | null, optional) · pattern ^[A-Za-z0-9_-]{1,128}$
result ("passed" | "failed", required)
method ("passkey" | "mfa" | "turnstile" | "own_approval" | "other", optional)

JSON

{
  "sessionToken": "PASTE_BROWSER_SESSION_TOKEN",
  "actionId": "export_report",
  "targetId": "report_1042",
  "result": "passed",
  "method": "passkey"
}

Responses

200: Success · body StepUpResult
400: bad_request: the request is invalid; message says what to fix and field names the request field · body Error
401: unauthorized (missing or invalid server key, missing Bearer scheme, or a malformed or unsigned session token) or session_reinit_required (a token this collector issued whose session expired, was revoked or was removed); use the code to distinguish · body Error
403: forbidden: the server key and session token belong to different Sites, or the call came from a browser page · body Error
404: not_found: unknown path, or an ID in the path that is not on this Site · body Error
409: step_up_not_held (the decision is not waiting for review), step_up_mismatch (another session, action or target), step_up_settled (already approved or rejected) or step_up_expired (more than 15 minutes after the hold) · body Error
413: payload_too_large: the request body exceeds 131072 bytes · body Error
429: rate_limited: wait for Retry-After · body Error · headers Retry-After
500: internal_error: fail the protected action; do not retry automatically · body Error
503: service_unavailable: temporarily unavailable; only verify retries · body Error

Success body fields

decisionId (string, required)
actionId (string, required) · pattern ^[A-Za-z0-9_-]{1,64}$
targetId (string | null, required)
sessionId (string, required)
stepUp ("passed" | "failed", required)
method ("passkey" | "mfa" | "turnstile" | "own_approval" | "other", required)
proceed (boolean, required): true only for a pass: the hold is approved and used once. Still run your own authorization before the write.
resolvedAt (number, required): Unix epoch milliseconds.
replayed (boolean, required)
note (string, required)

Failures are not verdicts. Error bodies follow the Error schema: code is one of bad_request, unauthorized, session_reinit_required, forbidden, not_found, conflict, identity_required, payload_too_large, rate_limited, internal_error, service_unavailable, request_failed, approval_invalid, approval_used, approval_expired, approval_mismatch, step_up_not_held, step_up_mismatch, step_up_settled, step_up_expired, step_up_superseded, agent_tokens_disabled, tool_not_approved, tool_not_read_only. Errors and retries explains each code and what to do.

Example

curl

curl -sS -X POST 'https://app.trytelltale.dev/api/v1/decisions/decision_PASTE_DECISION_ID/step-up' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"sessionToken":"PASTE_BROWSER_SESSION_TOKEN","actionId":"export_report","targetId":"report_1042","result":"passed","method":"passkey"}'

fetch

const response = await fetch("https://app.trytelltale.dev/api/v1/decisions/decision_PASTE_DECISION_ID/step-up", {
  method: "POST",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "sessionToken": "PASTE_BROWSER_SESSION_TOKEN",
    "actionId": "export_report",
    "targetId": "report_1042",
    "result": "passed",
    "method": "passkey"
  }),
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();

Machine-readable contract: openapi.json. Request builder: the API explorer shows every operation as curl; it sends requests only on a local dashboard.

Report the result of your own step-up check for a held decision

#Authentication

#Parameters

#Request body

#Responses

#Success body fields

#Example