Verify evidence before a protected action

View as Markdown

POST /api/v1/verify · operationId verifyProtectedAction

For developers: your server sends this request with a server key; it is not a button in the dashboard.

Apply your own authenticated account authorization and the returned decision. Unknown is not human. Optionally forward the incoming request’s Web Bot Auth headers to receive signed attribution. The server adapter retries valid 503 service_unavailable, config_unavailable or session_unavailable responses, and once on a 408/429 whose Retry-After fits, at most three attempts within one five-second deadline; it never executes the protected application action.

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

Request body

Content-Type: application/json (required)

JSON
{
  "sessionToken": "PASTE_BROWSER_SESSION_TOKEN",
  "actionId": "export_report",
  "targetId": "report_1042",
  "userId": "usr_123",
  "accountId": "acct_456"
}

Responses

Success body fields

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/verify' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"sessionToken":"PASTE_BROWSER_SESSION_TOKEN","actionId":"export_report","targetId":"report_1042","userId":"usr_123","accountId":"acct_456"}'
fetch
const response = await fetch("https://app.trytelltale.dev/api/v1/verify", {
  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",
    "userId": "usr_123",
    "accountId": "acct_456"
  }),
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();
Node adapter
// server.js is the server adapter: download /adapters/v1/server.js (see Server adapters).
import { createTelltaleServer } from './lib/telltale/server.js';

const telltale = createTelltaleServer({ endpoint: "https://app.trytelltale.dev", serverKey: process.env.TELLTALE_SERVER_KEY });
const result = await telltale.verify({
  "sessionToken": "PASTE_BROWSER_SESSION_TOKEN",
  "actionId": "export_report",
  "targetId": "report_1042",
  "userId": "usr_123",
  "accountId": "acct_456"
});

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