Public API Reference
Complete reference for the Vouched KYA REST API
Overview
The Vouched KYA Public API provides programmatic access to detection services, project data, analytics, governance, and the platform's supporting surfaces. Endpoints are RESTful and use JSON. Most endpoints require API key authentication; the public client-ingestion endpoints (/pixel, /pixel/track) authenticate by project/pixel ID in the request body, and the gateway, Molti, and audit families each authenticate by their own flow instead: see Authentication.
Scope of this reference. It documents the public /api/v1 surface end to end: core detection,
events, pixels, projects, Shopify, enforcement, policy, webhooks, Bouncer (Govern), audit,
gateway, managed-agent (Molti), OpenClaw, vault, fingerprint, and the supporting infrastructure
endpoints. Deliberately not covered, because they authenticate with a dashboard session or
admin rights (or are internal edge plumbing): the gateway connection, domain, install, and .mcpb
routes; the Molti deploy, restart, stop, and API-key rotation routes; the Wink identity routes
(wink/session, wink/verify); and everything under /api/internal/*, which backs the dashboard
itself. If an endpoint isn't documented here, treat it as unsupported rather than undocumented.
A machine-readable OpenAPI 3.1 description of the endpoints below is served at GET /api/v1/openapi.json (no authentication); it is generated from the same Zod schemas the routes validate with, and CI fails when the committed document drifts from them.
Base URL
All API requests should be made to:
https://kya.vouched.id/api/v1For local development:
http://localhost:3000/api/v1Authentication
Vouched KYA uses API keys to authenticate requests. See Credentials for where to find your Project ID and API key.
Include your API key in the request header:
curl -X POST https://kya.vouched.id/api/v1/detect \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"userAgent": "Mozilla/5.0..."}'Project-scoped and organization-wide keys
A project-scoped key works only on its own project. An organization-wide key (one with no project scope) works on every project its owner can see, but on each project it can do no more than its owner's role there allows:
- A request that needs
readpermission needs only that the owner can see the project. - A request that needs
writepermission also needs the owner to be able to edit the project: an organization owner or admin, the project's owner, or a project admin or editor. - A request that needs
adminpermission also needs the owner to be able to manage the project's API keys: an organization owner or admin, the project's owner, or a project admin.
Otherwise the request is refused. The check uses the owner's role at the time of the request, so a role change applies to their existing keys right away.
Which endpoints need a key?
Exceptions inside /bouncer/* (each authenticated by its flow rather than an API key, by design): the user-facing consent link (GET /bouncer/authorize) and delegation status polling (GET /bouncer/delegations/status/{requestId}) are public; delegation token retrieval authenticates with Authorization: Bearer <delegation_token>; delegation creation (POST /bouncer/projects/{projectId}/delegations) is part of the browser-based consent flow; the OAuth callback (GET /bouncer/oauth/callback) is the provider's redirect target, validated by its state parameter; and the OAuth result (GET /bouncer/oauth/result) hands the delegation the callback created to the browser once, for a single-use, browser-bound ticket. The OpenClaw consent endpoint (/openclaw/consent/{requestId}) takes the consent token minted by its approval webhook and a signed-in Vouched KYA account in the project's organization.
Core Detection APIs
Detect AI Agent
Analyzes a request to determine if it originates from an AI agent, bot, or human.
Endpoint: POST /api/v1/detect
Auth: API key (X-API-Key), read permission.
Request:
{
"userAgent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot",
"ipAddress": "203.0.113.7",
"headers": {
"accept": "*/*"
},
"url": "https://example.com/pricing",
"method": "GET"
}Only userAgent is required. Optional fields: ipAddress (the visitor address your server observed, as one IPv4 or IPv6 address; a comma-separated value such as an X-Forwarded-For chain records no address, and when omitted or rejected the detection carries no IP and no network intel), headers, url, method, behavioralData, requestId, timestamp, and options (mode: strict | balanced | lenient, includeMetadata, includeBreakdown).
Limits:
A body over 1 MiB answers 413 API_REQUEST_TOO_LARGE and is not read past the limit. A field over
its limit answers 400 VALIDATION_INVALID_REQUEST, and the error's details.validation names the
field.
Response (values are illustrative):
{
"success": true,
"data": {
"result": {
"isAgent": true,
"confidence": 98,
"detectionClass": { "type": "AiAgent", "agentType": "ChatGPT" },
"reasons": ["User-Agent matched known agent pattern: ChatGPT"],
"signals": [
{
"signalType": "pattern",
"confidence": 90,
"weight": 0.5,
"source": "user_agent_pattern",
"explanation": "User-Agent matched known agent pattern: ChatGPT"
}
],
"detectedAgent": { "type": "AI", "name": "ChatGPT" },
"verificationMethod": "pattern",
"timestamp": "2026-07-27T12:00:00.000Z"
},
"metadata": {
"processingTime": 12,
"wasmUsed": true,
"cacheHit": false
}
},
"metadata": {
"requestId": "req_abc123",
"timestamp": "2026-07-27T12:00:00.000Z"
}
}data.result is the detection detail. data.breakdown (a per-method confidence breakdown) is included when options.includeBreakdown is set, and data.behavioralAnalysis (isHumanLike, confidence, patterns, anomalies) is included when the request carried behavioralData.
Detection Classes:
result.detectionClass is a tagged object: match on its type:
The wire schema also declares Automation and Unknown, but the detection engine never emits either: treat them as dead values, not classes to branch on.
Confidence Scores:
Scores range from 0–100. See Confidence Scores for the bands to choose a threshold from.
Errors: 401 AUTH_MISSING_CREDENTIALS / AUTH_INVALID_API_KEY / AUTH_EXPIRED_API_KEY (see
Common Error Codes for the shared shape), 429 RATE_LIMIT_EXCEEDED once
your plan's per-minute limit is exceeded, 415 API_CONTENT_TYPE_NOT_SUPPORTED when the body is
not sent as Content-Type: application/json, 400 VALIDATION_BAD_REQUEST when it is not valid
JSON, 400 VALIDATION_INVALID_REQUEST when the body fails schema validation (e.g. missing
userAgent) or a field is over its limit, and 413 API_REQUEST_TOO_LARGE when the body is over
1 MiB (see Limits above).
Event Tracking (retired)
POST /api/v1/event and POST /api/v1/batch are retired.
They answer every request with 410 Gone and API_ENDPOINT_RETIRED, whatever the body or credentials, and will be removed after one release cycle.
The response uses the standard error envelope; error.details.replacements lists the routes to use instead:
{
"success": false,
"error": {
"code": "API_ENDPOINT_RETIRED",
"message": "POST /api/v1/event has been retired. Send page events to POST /api/v1/pixel or POST /api/v1/beacon.",
"details": { "replacements": ["/api/v1/pixel", "/api/v1/beacon"] }
},
"metadata": { "timestamp": "2026-10-21T12:00:00.000Z" }
}The /event response carries the public CORS headers (Access-Control-Allow-Origin: *), so a page that still calls it can read the error.
Pixel Tracking
Pixel Endpoint
Ingestion endpoint for the Marketing Pixel: the endpoint the pixel JS beacon calls on every page load.
Endpoint: POST /api/v1/pixel
Auth: Public: authenticated by the project/pixel ID (pixelId or projectId) in the body.
Request: a JSON pixel-tracking request: pixelId/projectId, sessionId, url, userAgent, plus optional behavioral and fingerprint signals. This endpoint's request schema (PixelTrackingRequestSchema) is large and internal to the beacon package; it is not itemized field-by-field here. Build against the Marketing Pixel beacon rather than this raw endpoint.
Response: a JSON detection result (classification + confidence). This endpoint is POST/JSON: it does not serve a 1×1 tracking GIF.
Errors: 400 MISSING_PIXEL_ID when pixelId is empty, 400 PROJECT_NOT_FOUND for an
unrecognized project/pixel ID (this endpoint returns 400, not 404, for that case, it's the
one exception among the project-scoped endpoints on this page), 401 AUTH_INVALID_API_KEY when a
proxied request's X-API-Key is invalid, read-only, not scoped to this project, or arrives without
KYA-Forwarded-IP (see Forward edge evidence), 429 RATE_LIMIT_EXCEEDED.
Shopify Pixel Track
Ingestion endpoint for the Shopify Web Pixel Extension: receives storefront events (page_view, product_view, cart_view, and similar) and stores each one as a detection so it appears in Analytics. Detection runs server-side from the request's own User-Agent and headers, because Shopify's sandboxed pixel environment cannot run client-side fingerprinting; accuracy is lower than the standard pixel beacon.
Endpoint: POST /api/v1/pixel/track
Auth: Public, authenticated by the projectId in the body (accepts a project UUID or its friendlyId). CORS is open (Access-Control-Allow-Origin: *) and OPTIONS preflight is supported.
Request:
{
"projectId": "acme-corp",
"sessionId": "session_abc",
"eventType": "page_view",
"timestamp": "2026-07-27T12:00:00.000Z",
"data": {
"url": "https://store.example.com/products/widget",
"pathname": "/products/widget",
"referrer": "https://google.com",
"title": "Widget",
"product": { "id": "123", "title": "Widget" },
"cart": { "totalQuantity": 2 },
"checkout": { "token": "chk_abc", "order": { "id": "456" } }
},
"metadata": { "source": "shopify-web-pixel", "version": "1.0.0" }
}Required fields: projectId, sessionId, eventType. Optional fields: timestamp (ISO 8601), correlationId (cross-surface correlation id, validated and normalized server-side), data (every field optional, extra keys preserved), and metadata (source, version, extra keys preserved).
Response:
{
"success": true,
"eventId": "d4c0f6f2-5678-90ab-cdef-1234567890ab",
"sessionId": "session_abc",
"processingTime": 45
}eventId is a server-generated acknowledgment id, not the stored detection's id. The detection verdict is not returned on this endpoint; results appear in the dashboard.
Rate limits: requests are limited per client IP + project at the Free-plan limits regardless of your plan, because this endpoint is unauthenticated. A 429 carries X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers.
Errors: 400 INVALID_JSON for an unparsable body, 400 VALIDATION_ERROR with a per-field details array when the payload fails validation, 404 PROJECT_NOT_FOUND for an unrecognized projectId, 429 RATE_LIMITED, 500 PIXEL_CREATION_FAILED when the project's default pixel record can't be created or found, 500 INTERNAL_ERROR on an unexpected failure.
This endpoint's rate-limit error code is RATE_LIMITED, not the RATE_LIMIT_EXCEEDED used
elsewhere in the API.
Log Detection
Records detections produced by your SDK or edge code so they appear in your dashboard and Analytics.
Endpoint: POST /api/v1/log-detection
Auth: API key (X-API-Key) scoped to a project, read permission.
Request: one detection record or an array of up to 500 (LogDetectionRequestSchema). Send an eventId (UUID) and context.timestamp with every record, minted once per event and resent unchanged on every retry, so a retried record is stored once. The body may be gzip-compressed (Content-Encoding: gzip) and may not exceed 4 MiB once decoded. A timestamp more than five minutes ahead of the server, or more than 14 days behind it, is refused. If your clock is off, send X-Checkpoint-Clock-Offset: whole minutes from -1440 to 1440 added to every timestamp (six minutes fast sends -6), the same on every retry.
Response: 202 Accepted once the records are written, with the result of every record in outcomes, in request order. eventId is null when the client sent none or a non-UUID:
{
"success": true,
"message": "Detection log accepted",
"processingTimeMs": 12,
"outcomes": [
{ "index": 0, "eventId": "3f2c8a10-5b7d-4c1e-9a64-0d2b7e8f1a35", "status": "stored" },
{ "index": 1, "eventId": "9a1d4e70-2c83-4b5f-8e19-6f0a3c7d2b48", "status": "duplicate" },
{
"index": 2,
"eventId": null,
"status": "refused",
"reason": "invalid_record",
"issues": [{ "path": "eventId", "message": "Invalid UUID" }]
}
]
}A record that fails validation never blocks the rest of an array: it is refused alone, issues lists up to 20 failing fields, and every valid record is stored. The refused array and discarded count from earlier versions are still returned.
Errors: 401 AUTH_MISSING_CREDENTIALS / AUTH_INVALID_API_KEY (also when the key has no project) / AUTH_EXPIRED_API_KEY; 403 PERMISSION_INSUFFICIENT (the key lacks read); 400 VALIDATION_INVALID_REQUEST (a single record fails validation, or the body is not an object or array); 400 VALIDATION_BAD_REQUEST (more than 500 records, or not valid JSON); 413 (over 4 MiB); 415 (Content-Encoding other than gzip or identity); 503 SERVICE_UNAVAILABLE_TRANSIENT (the write failed and the body has no outcomes: resend the whole array unchanged).
Project Management
List Projects
Get all projects associated with your API key.
Endpoint: GET /api/v1/projects
Auth: API key (X-API-Key). A project-scoped key returns exactly its project; an unscoped key
returns every project across the key owner's organizations. Permission scope (read / write /
admin) does not affect list visibility: it gates what you may do, not what you can see here.
Request: query parameters (no body):
Response:
List endpoints return a paginated envelope: the array is always under data:
{
"success": true,
"data": [
{
"id": "acme-corp",
"name": "My Project",
"createdAt": "2024-01-01T00:00:00.000Z",
"status": "active",
"stats": {
"pixelCount": 2,
"detectionCount": 1234,
"lastDetection": "2024-01-07T09:30:00.000Z"
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 50,
"totalPages": 3,
"hasMore": true
},
"version": "v1",
"timestamp": "2026-07-27T12:00:00.000Z"
}status is active when the project has at least one pixel, otherwise inactive.
Errors: 401 AUTH_MISSING_CREDENTIALS / AUTH_INVALID_API_KEY for missing or invalid keys.
Get Project Details
Endpoint: GET /api/v1/projects/{projectId}
Auth: API key (X-API-Key) with access to this specific project.
Request: no body or query parameters. {projectId} accepts the project UUID or its
friendlyId.
Response:
{
"success": true,
"data": {
"id": "acme-corp",
"name": "My Project",
"createdAt": "2024-01-01T00:00:00.000Z",
"status": "active",
"stats": {
"pixelCount": 2,
"detectionCount": 1234,
"lastDetection": "2024-01-07T09:30:00.000Z"
}
},
"version": "v1",
"timestamp": "2026-07-27T12:00:00.000Z"
}Errors: 403 PERMISSION_FORBIDDEN when your API key isn't scoped to this project, 404 PROJECT_NOT_FOUND when the project doesn't exist.
Delete Project
Endpoint: DELETE /api/v1/projects/{projectId}
Auth: API key (X-API-Key) with admin permission and access to this specific project.
Admin permission alone is not enough: the key's owner must also pass the standard delete
permission check for the project (owner or organization role), or the call must be a partner
teardown (an unscoped key owned by a partner service account, deleting a project created
through the managed one-click path).
Deletes the project and tears down its managed infrastructure (dispatch worker and KV namespaces, best effort). Built for cross-app integrations that must not orphan superseded projects.
Request: no body or query parameters. {projectId} accepts the project UUID or its
friendlyId, same as GET.
Response:
{
"success": true,
"data": {
"projectId": "b3f4c2d1-0000-4000-8000-000000000000",
"friendlyId": "acme-corp"
},
"metadata": {
"requestId": "req_1690000000000_abc123",
"timestamp": "2026-07-27T12:00:00.000Z",
"version": "v1"
}
}friendlyId is null when the project had none.
Errors: 403 PERMISSION_INSUFFICIENT when the key lacks admin, 403 PERMISSION_FORBIDDEN
when the key isn't scoped to this project, 403 PERMISSION_DENIED when neither the delete
permission check nor the partner-teardown rule allows the caller, 404 PROJECT_NOT_FOUND when the
project doesn't exist, 500 TRANSACTION_FAILED / UNKNOWN_ERROR / DELETE_FAILED when the
delete service fails.
Get Project Detections
Endpoint: GET /api/v1/projects/{projectId}/detections
Auth: API key (X-API-Key) with access to this specific project, read permission.
{projectId} accepts the project UUID or its friendlyId: friendlyIds are resolved before the
access check, so a project-scoped key works with either form. An unknown project returns
404 PROJECT_NOT_FOUND; an existing project outside your key's scope returns 403.
Request: query parameters (no body):
Response:
{
"success": true,
"data": [
{
"id": "det_123",
"timestamp": "2024-01-01T12:00:00.000Z",
"isBot": true,
"confidence": 0.92,
"botType": "ChatGPT",
"userAgent": "Mozilla/5.0...",
"url": "https://example.com"
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1000,
"totalPages": 20,
"hasMore": true
},
"version": "v1",
"timestamp": "2026-07-27T12:00:00.000Z"
}On this endpoint confidence is normalized to 0–1 (a 92%-confidence detection is 0.92). The
/detect endpoint returns confidence on the 0–100 scale, and so does the extended view below.
Errors: 403 PERMISSION_FORBIDDEN when your API key isn't scoped to this project, 400 VALIDATION_INVALID_START_DATE / VALIDATION_INVALID_END_DATE / VALIDATION_INVALID_DATE_RANGE
for malformed or inverted date filters.
Extended view (?view=extended)
Pass view=extended (or its alias include=signals) to receive the evidence-grade projection: everything Vouched KYA stores about
each detection that is safe to return, with per-field nullability (which fields populate depends on
the installation surface that wrote the row, see
Installation Surfaces).
Additional query parameters (all optional except that postureOutcome and sessionRotation each need a startDate; validation is strict: an unknown enum value, a
limit above 100, or a page above 200 is a 400 VALIDATION_ERROR, not a silent clamp; an
empty value like ?sessionId= is treated as absent). Default page pagination is windowed: total saturates
at min(20,000, 200 × limit) rows per filter slice (10,000 at the default limit=50), and
totalPages/hasMore are derived from that saturated total, so following the envelope never
requests a page the validator refuses. Narrow the filters or date window, or use cursor mode below for deeper history.
Read deeper history with a cursor
Start with ?view=extended&pagination=cursor&limit=100. To continue, add the returned
nextCursor as the URL-encoded cursor parameter. Keep the same project, normalized filters
and page size. A cursor without pagination=cursor, or a cursor-mode page other than 1,
returns 400 VALIDATION_ERROR.
With postureOutcome or sessionRotation and no endDate, cursor mode measures the 7-day window up
to the bound that the first request froze, so a continuation stays valid however long paging takes.
For example, resume with ?view=extended&pagination=cursor&limit=100&cursor=<nextCursor>;
replace <nextCursor> with the value that the previous response returned.
Cursor responses keep the same success envelope and extended data[] records. Their pagination
object contains only limit, hasMore and nextCursor. It omits page, total and totalPages.
The final or empty page has hasMore: false and nextCursor: null:
{
"success": true,
"data": [],
"pagination": { "limit": 100, "hasMore": false, "nextCursor": null },
"version": "v1",
"timestamp": "2026-10-17T12:00:00.000Z"
}Rows are ordered by timestamp and ID, newest first, preserving PostgreSQL microseconds in the continuation state. The first request freezes an upper timestamp from database time. Later pages exclude rows newer than that bound. Deleted rows disappear, even when the deleted row was the previous page's seek anchor. This is not an immutable transactional snapshot.
Invalid encoding, unsupported cursor state, a future or inverted timestamp bound, or a mismatch
with the project, filters or page size returns 400 VALIDATION_ERROR. Treat the cursor as opaque
and pass it unchanged. It is unsigned base64url-encoded continuation state, not an authorization credential.
Each request still requires a valid API key with access to the project. A key scoped to another
project receives 403 PERMISSION_FORBIDDEN before cursor validation.
Visitor session vs. consolidated session. sessionId here is the cookie value the browser
actually carried (_as_beacon_session, minted by the pixel or the beacon SDK): one id shared
across every surface a single visit touched (pixel, beacon, gateway, and the Java SDK; the .NET
and TS middleware adapters are a follow-up), so ?sessionId=<uuid> returns pixel, beacon, and
gateway rows for one visitor together. consolidatedSessionId is a different, server-derived key
(class-partitioned by design): it is what GET /api/v1/projects/{projectId}/sessions/{consolidatedSessionId}
takes, and it does not match across detection classes the way sessionId now does. Non-browser
traffic (no cookie, a bare curl, a crawler, a server-to-server SDK call) still gets a random
per-request sessionId, exactly as before.
The network field returns the stored network object unchanged, or null when none was stored.
It can include optional proxyAssertions and proxyCollectionState, including the vendor source
identifier and nullable timing and quality fields, and an optional ipRoutingType (cellular,
satellite, datacenter, fixed or anonymizer). These are retained detection data exposed by
the authorized project API, subject to the same access controls, IP privacy handling and retention
policy as the row. Older rows can omit all three fields. Empty or missing assertions do not mean a clean
address, and a legacy proxy positive does not establish confirmed current evidence. See
Stored proxy assertions for the field contract and
current provider limits. This contract also applies to single-detection extended read-back.
The entropyAvailability field reports, per browser signal, whether the beacon's collector produced a value: an object keyed by signal id, each value { "status": "ok" | "empty" | "timeout" | "absent" }. ok means a usable value was collected, empty that the collector ran and produced nothing usable, timeout that it did not finish in time, and absent that it was not run. Only the statuses the browser reported are returned, never the values. The field is null when the browser reported no valid status, which means unknown, not absent.
Response (data[] items; the pagination object depends on pagination=page or pagination=cursor):
{
"id": "det_123",
"timestamp": "2026-09-01T12:00:00.000Z",
"detectionClass": "bot",
"confidence": 95,
"agentName": "GPTBot",
"agentCategory": "scraper",
"verificationMethod": "pattern",
"assurance": "anonymous",
"riskLevel": "high",
"reasons": ["User-Agent matched known agent pattern: GPTBot"],
"userAgent": "Mozilla/5.0...",
"ipAddress": "20.171.207.1",
"url": "https://example.com/signup",
"requestPath": "/signup",
"geo": { "country": "US", "region": "CA", "city": "San Jose", "asn": 8075, "isp": "..." },
"sessionId": "sess_abc",
"correlationId": "4bf92f3577b34da6a3ce929d0e0e4736",
"decision": { "action": "block", "reason": "deny_list_match", "policyId": "deny-scrapers" },
"engine": { "name": "checkpoint-engine-wasm", "version": "0.2.0", "rulesetVersion": "0.2.0" },
"sdk": { "name": "@kya-os/checkpoint-nextjs", "version": "1.8.0", "runtime": "node" },
"latencyMs": 41,
"network": null,
"signals": { "transport": { "tlsJa4": "..." }, "client": { "attributes": {} }, "behavioural": {} }
}The extended view returns confidence on the canonical 0–100 scale. Only the legacy default
view rescales to 0–1. Internal scoring values are never included in any view.
Two contract notes for the extended view: every validation failure (malformed or inverted dates
included) returns 400 with error.code exactly VALIDATION_ERROR and per-parameter
details.issues (the VALIDATION_INVALID_* codes above apply to the legacy view only). And
legacy rows may carry deprecated detectionClass values (automation, unknown) in responses;
the filter accepts only the four current values.
Get Detection by ID
Endpoint: GET /api/v1/detections/{id}
Auth: API key (X-API-Key), read permission. The key must have access to the project the
detection belongs to (a project-scoped key reaches only its project; any other key reaches the
projects its owner can see, admin permission included).
Single-record, full-evidence read-back: returns the same extended projection as
?view=extended above (one mapper, one scrubber; the two surfaces cannot drift), wrapped in the
standard v1 success envelope. This is the deep-link target for "why was this classified"
questions and support tickets.
Response:
{
"success": true,
"data": {
"id": "4bf92f35-77b3-4da6-a3ce-929d0e0e4736",
"timestamp": "2026-09-01T12:00:00.000Z",
"detectionClass": "bot",
"confidence": 95,
"agentName": "GPTBot"
},
"version": "v1",
"timestamp": "2026-09-01T12:05:00.000Z"
}(data carries every extended-view field; abbreviated here.)
404 by design
A nonexistent id, a malformed id, and a detection belonging to a project your key cannot access
all return the same 404 DETECTION_NOT_FOUND. The endpoint never answers 403 or 400 for the
id, so it cannot be used to probe which detection ids exist or who owns them.
Get Project Session
Endpoint: GET /api/v1/projects/{projectId}/sessions/{consolidatedSessionId}
Auth: API key (X-API-Key), read permission, with access to the project. projectId can be
the UUID or the friendly id.
Reads back one consolidated session: the key a live Beacon 202 returns as sessionId and the
posture token carries as session_id. data has the session's verificationTier,
verifiedVendor, verifiedProtocol, verifiedSource, and signalStrength, plus the same
extended fields as Get Detection by ID for the session's latest detection.
Session fields can lag the receipt. A live Beacon 202 returns before the session drain applies the
batch, so verificationTier, verifiedVendor, verifiedProtocol, verifiedSource, and
signalStrength read null until the drain runs, normally within seconds and at the latest on the
next minute.
Consolidated sessions are split by detection class, so the id changes if a visit's class does. To
follow one browser visit across classes and surfaces, filter
Get Project Detections by sessionId instead.
An unknown or malformed session id and a session with no data both return
404 SESSION_NOT_FOUND; the endpoint never answers 400 for the id.
Get Project Analytics
Endpoint: GET /api/v1/projects/{projectId}/analytics
Auth: API key (X-API-Key) with access to this specific project. {projectId} accepts the
project UUID or its friendlyId (resolved before the access check).
Request: query parameters (no body):
Response:
{
"success": true,
"data": {
"period": "day",
"startDate": "2024-01-01",
"endDate": "2024-01-07",
"summary": {
"totalDetections": 10000,
"uniqueBots": 300,
"averageConfidence": 78.5
},
"timeSeries": [
{
"date": "2024-01-01",
"detections": 1500,
"bots": 75,
"humans": 1425
}
],
"botTypes": {
"chatgpt": 45,
"claude": 20,
"googlebot": 10
}
},
"version": "v1",
"timestamp": "2026-07-27T12:00:00.000Z"
}Errors: 400 INVALID_PERIOD for a period outside hour/day/week/month, 400 INVALID_START_DATE / INVALID_END_DATE / INVALID_DATE_RANGE for malformed or inverted date
filters, 500 ANALYTICS_FETCH_ERROR on a downstream aggregation failure.
Managed Deploy
Endpoint: POST /api/v1/deploy/managed
Auth: API key (X-API-Key) with admin permission.
Deploys a KYA-OS agent to Vouched KYA's managed hosting on behalf of an existing user, so the deployment appears in that user's dashboard. Built for cross-app integrations: this is not part of the normal dashboard deploy flow.
Request: the body takes projectName (required), template (default "blank"), enableReputation (default true), and at least one user identifier: userEmail or userGithubId. The user must already have a Vouched KYA account: the endpoint never creates accounts.
audit (optional) asks for protocol audit on the new deployment, in the shape the dashboard's deploy flow sends.
Without it the deployment has no protocol audit, and a deployment keeps the audit it was created with: a redeploy does not turn it on.
Response: 201 with { projectId, friendlyId, workerUrl, agentDid, ktaClaimUrl, audit, dashboardUrl }.
audit is { status, effectiveProfile } where status is ready, degraded (a lower assurance
profile than requested is active) or disabled; it is absent when audit is disabled for the
deployment. See Deploying a KYA-OS Server for the deployment models.
Errors: 403 PERMISSION_DENIED when the key is not a partner service key (unscoped and owned
by an allow-listed partner service account; admin permission alone is not enough), 400 VALIDATION_ERROR for a malformed body, 400 MISSING_USER_IDENTIFIER when neither userEmail nor
userGithubId is set, 404 USER_NOT_FOUND when no existing account matches the identifier (this
endpoint never creates one), 400 NO_ORGANIZATION when the matched user has no organization to
deploy into, 400 DEPLOY_FAILED (or a more specific code from the deploy service) on a failed
deployment.
Shopify Endpoints
Public, API-key-authenticated endpoints for the Shopify integration to read and update its own project. See that page for setup; this section documents the wire contract.
Get Shopify Project
Endpoint: GET /api/v1/shopify/projects/{projectId}
Auth: API key (X-API-Key) with access to this project, read permission.
Request: no body or query parameters. {projectId} accepts the project UUID or its
friendlyId.
Response: project id, friendlyId, name, domain, settings, stats
(pixelCount/detectionCount/lastDetection), createdAt, updatedAt: a simplified,
public-safe projection of the project record (no sensitive fields).
Errors: 404 PROJECT_NOT_FOUND when the project doesn't exist or was deleted, 403 PERMISSION_FORBIDDEN when your API key isn't scoped to this project.
Update Shopify Project
Endpoint: PATCH /api/v1/shopify/projects/{projectId}
Auth: API key (X-API-Key) with access to this project, write permission.
Request: { settings?: { blockOnHighConfidence?, confidenceThreshold?, enableSessionTracking?, enableWasm? } }: settings are merged with the project's existing settings, not replaced.
confidenceThreshold (0 to 1) also sets the project policy's block threshold (times 100), the one the dashboard policy editor shows and every enforcement path applies.
Response: the updated project's id, friendlyId, name, domain, settings, updatedAt.
Errors: 400 INVALID_REQUEST for unparsable JSON, 400 VALIDATION_ERROR for a body that fails
ShopifyProjectSettingsUpdateSchema, 404 PROJECT_NOT_FOUND, 403 PERMISSION_FORBIDDEN, 500 INTERNAL_ERROR when the update returns no row.
Get Shopify Project Stats
Endpoint: GET /api/v1/shopify/projects/{projectId}/stats
Auth: API key (X-API-Key) with access to this project, read permission.
Request: query parameters (no body):
Response: { totalRequests, blockedBots, allowedRequests, threatLevel, recentThreats, pagination }. threatLevel is low / medium / high, derived from the percentage of sessions
classified as AI agents. recentThreats is non-human sessions grouped by
consolidated_session_id, each with a pagesVisited count.
Errors: 404 PROJECT_NOT_FOUND, 403 PERMISSION_FORBIDDEN, 400 INVALID_DATE /
INVALID_DATE_RANGE for malformed or inverted date filters, 500 INTERNAL_DATABASE_ERROR /
STATS_FETCH_ERROR on a downstream failure.
Enforce API
Evaluate Request
Submit a request for enforcement evaluation against your project's policies. This is the endpoint the middleware SDKs call: the project is resolved from your API key, not the body.
Endpoint: POST /api/v1/enforce
Auth: API key (X-API-Key), read permission.
Request:
All fields are optional: send what you have:
{
"userAgent": "Mozilla/5.0...",
"ipAddress": "203.0.113.7",
"headers": {},
"path": "/api/data",
"method": "GET",
"options": {
"includeDetectionResult": true
}
}ipAddress takes one IPv4 or IPv6 address; a comma-separated value such as an X-Forwarded-For chain records no address. Other accepted fields: url, requestId, action ("get_policy" for a policy-only fetch, omit for detection + enforcement), source, and options.skipDetection / options.cacheTTL.
Limits:
A body over 256 KiB is not read past the limit.
The fields an SDK relays from the visitor's own request (userAgent, url, path, requestId and ipAddress) are never refused, so a visitor cannot choose the outcome by sending a long value.
Detection and policy read userAgent, url and path whole, so a path rule or a signature applies to the request the site serves; over its limit, such a value is cut to the limit where it is stored or echoed.
A requestId over its limit is cut to it, and an ipAddress over its limit records no address.
A requestId that a response header cannot carry (one holding a DEL, a character above U+007E, or a control character other than a tab, or one that starts or ends with a space or a tab) is replaced by sha256: followed by the lowercase hex SHA-256 of the whole id, in the response requestId and the X-Request-ID header, whatever its length. So is one whose cut to the limit would end in a space or a tab.
A field the SDK sets itself (method, action, source) over its limit answers 400 VALIDATION_INVALID_REQUEST, and the error's details.validation names the field.
The headers limits are observational: a request over one is served and logged, never refused or cut, since cutting could drop a signature or delegation header, and the 256 KiB body limit bounds the map.
The detection gateway's /__detect/enforce, where an SDK in edge mode sends this request, applies the same body limit and treats the relayed fields the same way; it stores and echoes none of them, and it does not check the method, action, source or headers limits.
Response:
{
"success": true,
"data": {
"decision": {
"action": "block",
"reason": "above_threshold",
"isAgent": true,
"confidence": 95,
"agentName": "ChatGPT-User",
"agentType": "chatgpt"
},
"processingTimeMs": 42,
"requestId": "req_abc123",
"detection": {
"isAgent": true,
"confidence": 95,
"detectionClass": "ai_agent",
"agentName": "ChatGPT-User",
"agentType": "chatgpt",
"verificationMethod": "pattern",
"reasons": ["User agent matched known AI agent pattern"]
}
}
}decision.action is one of allow, block, redirect, challenge, or log; rewrite is not part of this set. This endpoint layers two decision sources, and neither returns instruct: an
instruct verdict arrives as block.
- The project's policy settings (deny and allow lists, confidence threshold,
default_action) never returnchallengeeither: adefault_actionofinstructorchallengeis returned asblock. - A Cedar policy authored in Compose can override that decision, and it is the one source that
can return
action: "challenge", when the project has Cedar policy authoring enabled and the engine's decision is aChallenge. ItsInstructdecision is likewise returned asblock, with the machine-readable guidance folded intodecision.message, because the enforce response has noinstructvalue.
decision.redirectUrl and decision.message appear when relevant. The detection object is included only when options.includeDetectionResult is set, and there it carries the wire-form detectionClass (human | ai_agent | bot | incomplete_data).
The decision also rides on response headers, so middleware can act without parsing the body:
KYA-Enforce-Action: the decision actionKYA-Processing-Ms: server processing timeKYA-Detection-Method: which detection engine produced the verdict
Errors: 401 AUTH_INVALID_API_KEY when the API key has no associated project, 404 PROJECT_NOT_FOUND / 500 POLICY_FETCH_FAILED on the action: "get_policy" path if the project
can't be resolved, 400 VALIDATION_INVALID_REQUEST for a body that fails the schema or a
method, action or source limit above, 400 VALIDATION_BAD_REQUEST for a body that is not JSON, 413 API_REQUEST_TOO_LARGE for a
body over 256 KiB. 503 and 429 answer a request that can't be verified yet: error.code is
kyaos/identity-pending, kyaos/status-pending, kyaos/replay-state-unavailable or
kyaos/authorization-host-unavailable at 503, kyaos/replay-capacity at 429. Never let such a
request through. Each is final for that call, as in Outcomes and retries:
send later requests after Retry-After.
Fused Verdict
Combines a session id with the current request into one verdict and one recommended action. Use it when a browser session already produced evidence on another surface (the beacon, the pixel) moments earlier, and you want a later server-side check to account for it rather than scoring the new request alone.
Endpoint: POST /api/v1/verdict
Auth: API key (X-API-Key), read permission.
Request:
{
"sessionId": "session_abc",
"userAgent": "Mozilla/5.0...",
"ipAddress": "203.0.113.7",
"headers": {},
"path": "/api/data",
"method": "GET",
"attributes": {
"clientId": "web-app",
"surface": "checkout",
"marketSegment": "smb",
"userTier": "pro"
}
}sessionId is required: a string of 1 to 255 characters, such as a hashed person id plus client id and surface. Send an id that is unique to each visitor session, because calls that share a sessionId are judged together. A longer id is accepted, and the response sessionId carries sha256: and the lowercase hex SHA-256 of the whole id instead.
Every other field is optional and mirrors Evaluate Request: url, requestId, source. ipAddress takes one IPv4 or IPv6 address; a comma-separated value records no address. Relay the visitor's Cookie header in headers so the beacon's checkpoint_user cookie (legacy agentshield_user) identifies the device. options.includeBreakdown (boolean) adds breakdown to the response, and behavioralData (the object Detect AI Agent takes) adds behavioralAnalysis.
attributes is optional caller context. It never rejects a request, and it changes a verdict only on a project that turned on request-flag labelling; on those calls compare verdict.detectionClass, not verdict.confidence. Keep each entry flat: a key of 1 to 64 characters and a string, number or boolean value. Entries with null, object or array values are dropped, strings over 1,024 characters are truncated, and at most 32 entries and 10,240 bytes of serialized JSON are kept.
A non-blank userId entry identifies the visitor as a user in the dashboard. An id over 255 characters is stored as sha256: followed by the lowercase hex SHA-256 of the trimmed id.
If your edge terminates TLS or runs a bot challenge, send what it saw as top-level fields, the same evidence the beacon accepts as forwarded edge headers. Your API key vouches for them, the same as ipAddress, so send them only from your server, and never copy them from the visitor's own request. They count only when the key has the forward or write permission (or admin); a read-only key's values are ignored. A kya-forwarded-* entry inside headers is ignored.
Send whichever of these your edge has. A value that does not match its shape is ignored.
geoCountry, geoRegion, geoCity, geoAsn and geoIsp carry the visitor's location and network from your own edge. geoCountry is a two-letter ISO 3166-1 code such as US; geoRegion and geoCity are text of up to 100 characters; geoAsn is an autonomous system number such as 13335; geoIsp is a network operator name of up to 255 characters. All five are optional. They are stored with the detection, and when geoCountry, geoAsn or geoIsp is absent, Vouched KYA looks the stored value up from ipAddress. A malformed value is ignored. Location is not read from headers.
The response's network is Vouched KYA's own lookup on ipAddress, not what you sent: network.isp and network.geolocation never take your geoIsp or geoCountry. Your geoAsn is reported as network.deviceAsn, and your geoCountry feeds the network.timezoneMismatch and network.latencyMismatch checks.
IP geolocation by DB-IP (db-ip.com) and GeoNames (geonames.org), CC BY 4.0.
Send traceparent (or X-KYA-Correlation-Id) as an HTTP header to carry your own trace id. Verdict returns it as correlationId and in the X-KYA-Correlation-Id response header. traceparent is read first. Without either header, Verdict creates a new id for each request.
When the visitor's page runs the beacon, pass its KYA-Posture and KYA-Posture-Session headers (and DPoP, if the page sent one) in headers, unchanged. Send url and method as the browser called your backend. Forward posture to Verdict has the rules.
Limits:
These bound the shape of one request. Nothing limits how many requests you send.
A body over 1.25 MiB answers 413, and a body that is not valid JSON or not a JSON object answers 400. A missing sessionId, or a field of the wrong type (a number for userAgent, a header value that is not a string, a malformed event), still answers 400 VALIDATION_INVALID_REQUEST. A value over its limit is never refused, because these fields are relayed from the visitor's request: a string is cut to its limit, an event array keeps its first 2,000 entries, and headers keeps the entries inside the limits in the order sent and drops the rest (a header whose name or value is over its limit, entries past the 200th, and entries that would pass the 65,536 character total). A requestId over 1,024 characters, or one that a response header cannot carry (one holding a DEL, a character above U+007E, or a control character other than a tab, or one that starts or ends with a space or a tab), is replaced by sha256: followed by the lowercase hex SHA-256 of the whole id, in the response requestId and the X-Request-ID header, so a retry with the same id still matches. The row records which fields were cut or dropped and how many, never their values. A top-level field, a header value, a member of options or behavioralData, or an optional member of an event sent as null is treated as absent, as if you had left it out.
Retrying safely with requestId.
- Generate
requestIdon your server, once for each inbound visitor request you check. Never take it from a header or body field the visitor controls. - Retry once, with the same
requestIdand the same body, after a connection reset, a timeout or a504. Do not retry in any other case. - Set a short client timeout (2 seconds recommended) so the retry lands inside the 30-second window. Within 30 seconds of the first attempt, the retry gets that attempt's answer back: the same body with
replayedset totrue, and the sameX-KYA-Correlation-IdandX-KYA-Detection-Id. - A different body, a different
requestId, a call without arequestIdand a call after the 30 seconds are each a new call.
Response:
{
"success": true,
"data": {
"sessionId": "session_abc",
"correlationId": "5f3c7595497049709ba08c14b301329e",
"recommendedAction": "block",
"fraudDecision": "REJECT",
"reason": "above_threshold",
"verdict": {
"isAgent": true,
"confidence": 95,
"detectionClass": "ai_agent",
"agentName": "ChatGPT-User",
"agentType": "chatgpt",
"reasons": ["User-Agent matched known agent pattern: ChatGPT-User"]
},
"fusedFromPriorSession": true,
"error": "",
"explanation": { "engine": "ok", "evidence": { "source": "prior-session" } },
"detection": {
"isAgent": true,
"isBot": true,
"confidence": 95,
"detectionClass": { "type": "AiAgent", "agentType": "ChatGPT-User" },
"signals": [
{
"signalType": "pattern",
"confidence": 96,
"weight": 1,
"source": "user_agent_pattern",
"explanation": "User-Agent matched known agent pattern: ChatGPT-User"
}
],
"reasonCodes": ["detection/ua-pattern-match"],
"riskScore": 0.82,
"riskScoreSource": "uncalibrated",
"reasons": ["User-Agent matched known agent pattern: ChatGPT-User"],
"detectedAgent": { "type": "AI", "name": "ChatGPT-User" },
"agentType": "ChatGPT-User",
"botType": "ChatGPT-User",
"verificationMethod": "pattern",
"riskLevel": "high",
"assurance": "anonymous",
"metadata": { "processingTime": 12 },
"timestamp": "2026-10-27T12:00:00.000Z"
},
"metadata": { "processingTime": 12, "wasmUsed": true, "cacheHit": false },
"environment": { "incognito": false, "privacySettings": false },
"posture": { "status": "valid", "session": "8359c2e5-ccf3-46f6-9074-687dc12dbe21" }
},
"metadata": {
"requestId": "req_abc",
"correlationId": "5f3c7595497049709ba08c14b301329e",
"timestamp": "2026-10-27T12:00:00.000Z"
}
}recommendedAction and reason are the same enforcement-decision vocabulary as /enforce's decision.action and decision.reason. fusedFromPriorSession is true when earlier evidence for this sessionId on this project made the verdict stricter than this request's own detection would have: a session already read as suspect is not reset to clean by one quieter follow-up request. Otherwise this request's own detection drives the verdict.
fraudDecision is ACCEPT, REVIEW or REJECT, derived from recommendedAction.
error is empty on success, or one code: engine_unavailable, db_unavailable or network_intel_unavailable.
explanation says what the verdict rests on. explanation.engine is ok or failed. On failed the call has no detection result: apply your own default, unless the source is score. explanation.evidence.source is engine (this call), posture (your forwarded KYA-Posture token), score (a bot label added by your project's configuration), prior-session (an earlier call for this sessionId, as in fusedFromPriorSession) or none (nothing to classify: apply your own default).
Every 200 response carries an X-KYA-Detection-Id header: the id the detection for this call is stored under. Use it to look the detection up or to join a call to it.
verdict.reasons is the list of reasons for this request's detection (an empty array when there are none). verdict.basis says why the verdict reads as it does. Verdict reports one basis today: no_evidence (an incomplete_data verdict), meaning the request carried nothing to classify, such as a bare headless call. Verdict never reports client_interaction, because that basis needs interaction evidence and Verdict passes the engine none (behavioralData feeds behavioralAnalysis, not the engine). basis is absent on every other verdict, so a verdict without basis is a classification that rests on the request itself.
detection is this request's own engine read, in the same shape as data.result from Detect AI Agent: the per-signal breakdown and reason codes, riskScore, reasons, verificationMethod, riskLevel, assurance, isAiCrawler, botType and the structured detectionClass. On a call that your request flags labelled, riskScore, riskLevel, reasons and reasonCodes report that label's reading. A read the engine calls human carries the label Human in agentType and botType, while verdict.agentType stays absent. When fusedFromPriorSession is true, verdict and detection.isAgent, isBot, detectionClass, confidence, detectedAgent, agentType and botType all report the earlier evidence, while the signals, reason codes, risk score and the other fields still show what this request read on its own. detection.metadata carries detection_basis (see verdict.basis) next to processingTime. detection is omitted when the engine call failed or timed out; without a fused earlier session, verdict.detectionClass is then incomplete_data.
breakdown appears only when options.includeBreakdown is true, and behavioralAnalysis only when behavioralData was sent; both have the shapes Detect AI Agent returns, and breakdown describes the verdict, so it follows verdict when fusedFromPriorSession is true. data.metadata carries processingTime, wasmUsed (always true) and cacheHit (always false). The top-level metadata carries the request id (your requestId, else a generated one), correlationId and an ISO timestamp.
posture reports what Verdict did with the forwarded token. status is valid, invalid (with a reason), or absent (no KYA-Posture header). A valid token can raise suspicion on a human or incomplete-data read (to an agent, a bot, or incomplete data). It never lowers suspicion, and it never replaces an agent or bot that detection already found. An invalid token is ignored, and the call does not fail. posture is omitted when detection itself failed. For a test project, a valid token signed for a loopback page reports loopback: true: it can still raise suspicion, and it adds no environment, network or proof evidence.
environment reports incognito, privacySettings, virtualMachine, developerTools, tampering, antiDetect and osMismatch, as the visitor's browser reports them, when the forwarded KYA-Posture token carries them, and mitm (always true, with or without a token) when the User-Agent claims a browser but the forwarded TLS fingerprint belongs to known non-browser tooling.
Response fields
The members of data that an integration acts on. "Always" means every 200 carries it.
Outcomes and retries
A 200 carries a verdict. No other answer does, so apply your own default when a call ends without one.
A request the API rejects carries no verdict either, and retrying it does not help: fix the request. 400 VALIDATION_INVALID_REQUEST is a body that fails the schema (including a missing sessionId), 400 VALIDATION_BAD_REQUEST is a body that is not valid JSON, 401 AUTH_INVALID_API_KEY is an API key with no associated project, 404 PROJECT_NOT_FOUND is a project that cannot be resolved, and 413 API_REQUEST_TOO_LARGE is a body over 1.25 MiB.
Policy Endpoints
Get Customer Policy
Returns the detection policy for the authenticated project. Consumed by the checkpoint-wasm-runtime to enforce customer-defined policies at the edge.
Endpoint: GET /api/v1/policy (also HEAD /api/v1/policy for cache validation, headers only)
Auth: API key: X-API-Key header or Authorization: Bearer <api-key> (an api_key/apiKey query parameter is also accepted but not recommended). The key must be associated with a project.
Request: No parameters.
Response:
{
"projectId": "proj_abc123",
"denyList": ["did:web:agent.example.com", "BadBot"],
"allowList": ["GoodBot"],
"blockThreshold": 80,
"pathRules": [{ "pattern": "/health", "action": "allow" }],
"version": "m1x2y3z",
"updatedAt": "2026-07-27T12:00:00.000Z"
}Unlike most endpoints on this page, the policy object is the response body itself, not wrapped in a success/data envelope.
denyListmerges the project's Bouncer denied agents (client DID, agent DID, or client name), the pixel configuration'sblockedAgents, and the active checkpoint's deny list.allowListmerges the pixel configuration'sallowedAgentswith the active checkpoint's allow list, and is omitted entirely when empty.blockThresholdis the project policy's block threshold on the 0 to 100 scale, the one the dashboard policy editor sets and the gateway,/api/v1/enforceand/api/v1/verdictapply; the default is 80.pathRulesentries are{ pattern, action, agents? }withactiondeclared asallow,block, orchallenge; in the current implementation onlyallowrules are ever generated (from the pixel configuration'sskipPaths), and the field is omitted when there are none.versionis a base36 timestamp used for cache invalidation and echoed as theETag.
Responses carry Cache-Control: private, max-age=300 and an ETag; HEAD returns the same caching headers with no body.
Errors: 401 AUTH_MISSING_CREDENTIALS when no key is provided, 401 AUTH_INVALID_API_KEY for an invalid key or a key with no associated project, 401 AUTH_EXPIRED_API_KEY for an expired key, 404 PERMISSION_RESOURCE_NOT_FOUND when the project no longer exists.
Get Middleware Policy
Dedicated endpoint for middleware clients (checkpoint-dotnet, checkpoint-express, checkpoint-java) to fetch their project's enforcement policy as a flat DTO. This is the single source of truth for middleware policy responses.
Endpoint: GET /api/v1/middleware/policy (plus OPTIONS for CORS preflight)
Auth: API key (X-API-Key or Authorization: Bearer), read permission, project-scoped.
Request: No parameters; the project is resolved from the API key.
Response:
{
"success": true,
"data": {
"agent_did": null,
"denied_agents": ["did:web:agent.example.com"],
"allowed_agents": [],
"reputation_threshold": null,
"confidence_threshold": 80,
"default_action": "allow",
"redirect_url": null,
"claim_edge": null
}
}claim_edge is null unless the key has write permission and the project has an edge claim route. When present it holds project_id, url, credential and expires_unix: a resource SDK sends credential as a Bearer token and project_id as X-Project-Id to url to claim a proof single-use near the caller, and falls back to POST /api/v1/enforce/replay when the route answers 401 or 404.
agent_did and reputation_threshold are always null in the current implementation. Structured (v3.2) and legacy stored policies are both coerced to this flat wire shape. When default_action is redirect or instruct and the project has no explicit redirect URL, redirect_url is synthesized as https://kya.vouched.id/connect/{friendlyId}.
Responses are marked Cache-Control: private, no-store with Vary: Authorization, X-API-Key, X-Project-Id and an X-Request-ID header.
Errors: 401 AUTH_MISSING_CREDENTIALS / AUTH_INVALID_API_KEY / AUTH_EXPIRED_API_KEY for missing, invalid (including no associated project), or expired keys, 403 PERMISSION_INSUFFICIENT when the key lacks read permission, 404 PROJECT_NOT_FOUND when the key's project no longer exists.
Webhooks
Manage outbound webhook subscriptions for a project. Events are delivered as CloudEvents 1.0 envelopes signed with HMAC-SHA256.
Auth (all webhook endpoints): API key via X-API-Key header (Authorization: Bearer <key> also accepted). The key must be project-scoped: an unscoped key gets 400 VALIDATION_BAD_REQUEST ("API key must be scoped to a project to manage webhooks"). Requests are rate limited per key owner; responses carry X-Request-ID and X-API-Version: v1.
Envelope: success responses are { success: true, data, metadata: { requestId, timestamp, version: "v1" } }; errors are { success: false, error: { code, message, details? }, metadata }.
Shared errors (all webhook endpoints): 401 AUTH_MISSING_CREDENTIALS / AUTH_INVALID_API_KEY / AUTH_EXPIRED_API_KEY, 403 PERMISSION_INSUFFICIENT when the key lacks the required permission, 429 RATE_LIMIT_EXCEEDED from the rate limiter, which counts per key owner, 400 VALIDATION_BAD_REQUEST for a non-project-scoped key, 404 PERMISSION_RESOURCE_NOT_FOUND when the subscription id does not exist or belongs to another project.
On the create and update endpoints, a body that parses as JSON but fails schema validation (for
example a non-HTTPS URL, an unrecognized event type, or an empty update) is 400 VALIDATION_INVALID_REQUEST with error.message: "Invalid request data" and error.details
set to { validation: { "<field>": [messages] }, issues: [{ path, message, code }] }. The
remaining limitation is one step earlier: both routes read the body with a bare
request.json(), so a body that is not valid JSON at all surfaces as 500 INTERNAL_SERVER_ERROR (message hidden in production), not 400.
Subscription object
All endpoints that return a subscription use this serialization (the signing secret is never included after creation; reads show the fixed placeholder whsec_***):
{
"id": "0b7f6c9e-...",
"project_id": "b1c2d3e4-...",
"url": "https://example.com/hooks/checkpoint",
"event_types": ["detection.created"],
"secret": "whsec_***",
"description": "Prod notifications",
"status": "active",
"payload_mode": "full",
"is_internal": false,
"filters": { "minConfidence": 0.8 },
"rate_limit_per_min": 100,
"failure_count": 0,
"verified_at": "2026-08-19T12:00:00.000Z",
"last_delivery_at": "2026-08-19T12:05:00.000Z",
"created_at": "2026-08-19T11:59:00.000Z",
"updated_at": "2026-08-19T12:05:00.000Z"
}status is one of pending_verification, active, paused, disabled. Maximum 25 subscriptions per project.
The create and update schemas accept ten subscribable event types, but not all of them are produced today:
- Fire today:
detection.created,enforcement.decided(queued from the shared detection persistence boundary; see Delivery reliability). - Accepted but never emitted today:
detection.session_ended,delegation.created,delegation.revoked,delegation.expired. Nothing in the platform emits these; a subscription to them alone never receives a delivery. - Require the agent lifecycle harness:
agent.started,agent.heartbeat_lost,agent.stopped,agent.task_completed. These are wired through the agent lifecycle ingest, which nothing publishes to yet; they fire only once the harness that supervises agent processes ships.
Subscription filters apply to detection.* events only; they have no effect on enforcement.decided, delegation.*, or agent.* events even though they can be set alongside them.
Delivery format and signature verification
Deliveries are CloudEvents 1.0, structured JSON mode:
{
"specversion": "1.0",
"id": "evt_9f2c...",
"type": "detection.created",
"source": "https://kya.vouched.id/projects/{projectId}",
"subject": "det_123",
"time": "2026-08-19T12:00:00.000Z",
"datacontenttype": "application/json",
"dataschema": "https://kya.vouched.id/schemas/v1/detection.created",
"data": { "...": "event payload" }
}payload_mode: "compact" trims data to essential fields (id, projectId, classification/confidence for detection events, status/action for enforcement and delegation events, timestamps) and appends .compact to the dataschema URI.
detection.created full data (values are illustrative):
{
"id": "det_123",
"projectId": "b1c2d3e4-...",
"classification": "ai_agent",
"confidence": 0.98,
"agentType": "ChatGPT",
"isAgent": true,
"correlationId": "9f2c...",
"createdAt": "2026-08-19T12:00:00.000Z"
}confidence is the 0-1 float form of the stored 0-100 value. agentType and correlationId are null when the writer that produced the detection did not resolve them.
enforcement.decided full data (values are illustrative):
{
"id": "det_123",
"projectId": "b1c2d3e4-...",
"status": "enforced",
"action": "block",
"reason": "policy_match",
"policyId": "pol_abc",
"composedBlobHash": "sha256:...",
"correlationId": "9f2c...",
"detectionClass": "ai_agent",
"confidence": 0.98,
"agentName": "ChatGPT",
"createdAt": "2026-08-19T12:00:00.000Z",
"decidedAt": "2026-08-19T12:00:00.000Z"
}action is one of block, challenge, redirect, or instruct; this event never fires for allow/permit/log. reason, policyId, composedBlobHash, and agentName are null when the deciding layer didn't record them.
Every delivery carries three headers:
Verify by computing HMAC-SHA256(secret, timestamp + "." + rawBody) with your subscription secret, comparing against the header value (strip the sha256= prefix) using a timing-safe comparison, and rejecting timestamps older than your tolerance (the code comments recommend 5 minutes). Delivery requests use User-Agent: AgentShield-Webhooks/1.0.
Endpoint verification challenge: at creation, on URL change, and via the verify endpoint, Vouched KYA POSTs { "type": "webhook.verification", "challenge": "whk_verify_..." } to your URL with header X-Webhook-Verification: true. Your endpoint must respond 2xx with a JSON body echoing the same challenge value within 10 seconds. The challenge request itself is not HMAC-signed: at creation time you have not yet received the secret.
SSRF policy: webhook URLs must be HTTPS and must not resolve to private, loopback, link-local, or otherwise internal addresses. DNS is re-resolved before every outbound call and redirects are refused. A blocked URL returns 400 VALIDATION_BAD_REQUEST with a "Webhook URL is blocked" message.
Delivery reliability
detection.created and enforcement.decided are queued for delivery from a single shared persistence boundary that every online detection writer (pixel, pixel-track, beacon, /enforce, the gateway batch ingest route, and the shared log-detection ingest service) routes through, then delivered by a scheduled worker. This section documents the guarantees that pipeline actually provides.
Which detections fire detection.created. Every newly inserted detection emits the event, with one exception: a beacon/incomplete-evidence row (classification: "incomplete_data", or a normalized confidence of exactly 0) never does. Both conditions are checked independently; either one alone suppresses the event.
Which decisions fire enforcement.decided. Only a decision that was both an enforced action (block, challenge, redirect, or instruct) and actually applied. allow / permit / log decisions never fire it, and neither does an otherwise-enforced action recorded under an observe-mode policy (the decision was logged but the request was let through unchanged).
Delivery is at-least-once, not exactly-once. A retry, a worker restart mid-delivery, or a re-run of the same source write can cause the same logical event to be attempted more than once over the network. What the pipeline guarantees is a single durable logical delivery per (subscription, event type, source detection): retried fan-out for the same detection reuses the same X-Webhook-Id (a deterministic CloudEvent id derived from the detection id and event type), rather than enqueuing a second row. Use X-Webhook-Id as your deduplication key: if you receive it twice, discard the second delivery rather than double-processing it.
Ordering is not guaranteed. Events for different detections, or detection.created and enforcement.decided for the same detection, can arrive out of order (retries, worker concurrency, and per-subscription rate limiting can all reorder deliveries). Do not assume detection.created arrives before a later enforcement.decided for the same detection; key off the id in each event's data, not delivery order.
Retry schedule. A non-2xx response, a timeout, or a network error is retried with exponential backoff (base 2 seconds, doubling per attempt, capped at 30 minutes) plus up to 30% random jitter, for up to 5 attempts total by default before the delivery is marked terminally failed. Each delivery attempt times out after 15 seconds. Terminal failures do not retry further; they count toward the subscription's failure total and, at 10 consecutive terminal failures with no successful delivery in between, the subscription is automatically set to status: "disabled" (visible via GET /api/v1/webhooks/{id}; re-enable by updating its status back to active).
Per-subscription rate limit. Each subscription has a rate_limit_per_min (default 100, shown on the subscription object). A delivery that would exceed it is not counted as a failed attempt: it stays pending and is retried within roughly 10 seconds, without consuming a retry attempt or affecting the subscription's failure count.
Operators: the entire delivery pipeline (both enqueue and the delivery worker) is gated by a
single environment variable, WEBHOOKS_ENABLED. Setting it to anything other than "true" stops
new events from being queued and stops the worker from delivering rows already queued: it is the
kill switch for both directions, but it does not drain or discard rows already pending. Each
worker pass emits structured logs/counters for claimed, delivered, retried, terminally-failed,
rate-limited, and stale-claim-recovered rows (never logging secrets or full payloads), which is
the intended way to monitor queue lag and delivery health. There is no dedicated replay API for
terminally-failed deliveries today; recovering from a systemic outage on the receiving end
requires operator DB access to reset affected rows back to pending.
List Webhook Subscriptions
Endpoint: GET /api/v1/webhooks
Auth: API key (X-API-Key), project-scoped, read permission.
Request: no parameters.
Response: 200; data is an array of subscription objects for the key's project. Not paginated.
Errors: shared errors only.
Create Webhook Subscription
Endpoint: POST /api/v1/webhooks
Auth: API key (X-API-Key), project-scoped, write permission.
Request:
{
"url": "https://example.com/hooks/checkpoint",
"event_types": ["detection.created", "enforcement.decided"],
"description": "Prod notifications",
"payload_mode": "full",
"filters": {
"minConfidence": 0.8,
"agentTypes": ["ai_agent"],
"excludeAgentTypes": ["human"]
}
}url (required): HTTPS, SSRF-validated. event_types (required): at least one subscribable type. description: optional, max 500 chars. payload_mode: full (default) or compact. filters (optional): minConfidence is 0 to 1 and applies to detection.* events only; agentTypes / excludeAgentTypes are classification include/exclude lists.
The verification challenge is sent synchronously before the row is created: if your endpoint echoes the challenge, the subscription is created with status: "active"; otherwise status: "pending_verification".
Response: 201 with the subscription object plus secret, the raw whsec_... signing secret. This is the only time the secret is returned; store it now.
Errors: 429 RATE_LIMIT_QUOTA_EXCEEDED at the 25-per-project cap (a permanent cap, distinct from the transient RATE_LIMIT_EXCEEDED; details is { "limit": 25 }; free room by deleting a subscription), 400 VALIDATION_BAD_REQUEST for an SSRF-blocked URL, 400 VALIDATION_INVALID_REQUEST for a body failing schema validation (details carries the field errors), 500 INTERNAL_SERVER_ERROR for a body that is not valid JSON (see the note above), plus shared errors.
Get Webhook Subscription
Endpoint: GET /api/v1/webhooks/{id}
Auth: API key (X-API-Key), project-scoped, read permission.
Response: 200; the subscription object plus recent_events, the last 10 delivery attempts, each:
{
"id": "e5a1...",
"event_type": "detection.created",
"status": "delivered",
"response_status": 200,
"response_time_ms": 143,
"retry_count": 0,
"last_error": null,
"created_at": "2026-08-19T12:00:00.000Z",
"delivered_at": "2026-08-19T12:00:01.000Z"
}The set of status values for a delivery row is defined by the delivery pipeline, not this route; it is passed through verbatim from storage.
Errors: 404 PERMISSION_RESOURCE_NOT_FOUND for an id that does not exist or is owned by another project, plus shared errors.
Update Webhook Subscription
Endpoint: PATCH /api/v1/webhooks/{id}
Auth: API key (X-API-Key), project-scoped, write permission.
Request: any non-empty subset of url, event_types, description (nullable), payload_mode, filters (nullable; null resets to {}), status. status accepts only active or paused.
Rules enforced by the route:
statusandurlcannot change in the same request: URL changes trigger re-verification, which controls the status (400 VALIDATION_BAD_REQUEST).statuscan only be changed when the current status isactiveorpaused. Apending_verificationsubscription must be verified viaPOST /verify; adisabledone must be re-created (400).- The URL of a
disabledsubscription cannot be changed; delete and re-create (400). - A changed URL is re-challenged immediately: success sets
status: "active", resetsfailure_count, and stampsverified_at; failure setsstatus: "pending_verification".
Response: 200 with the updated subscription object.
Errors: 409 CONFLICT when the row was modified concurrently while this request was in flight (reload and retry; the explanation is in error.details.message, while error.message is the generic Resource conflict), 400 VALIDATION_BAD_REQUEST for the rule violations above or an SSRF-blocked URL, 400 VALIDATION_INVALID_REQUEST for a body failing schema validation, including an empty update (details carries the field errors), 404 PERMISSION_RESOURCE_NOT_FOUND, 500 INTERNAL_SERVER_ERROR for a body that is not valid JSON (see the note above), plus shared errors.
Delete Webhook Subscription
Endpoint: DELETE /api/v1/webhooks/{id}
Auth: API key (X-API-Key), project-scoped, write permission.
Response: 200 with { "deleted": true }. Stored delivery events are removed with the subscription.
Errors: 404 PERMISSION_RESOURCE_NOT_FOUND, plus shared errors.
Rotate Webhook Secret
Endpoint: POST /api/v1/webhooks/{id}/rotate-secret
Auth: API key (X-API-Key), project-scoped, write permission.
Response: 200 with { "secret": "whsec_...", "message": "..." }. The new raw secret is shown only in this response. Rotation is immediate: deliveries signed after this call use the new secret, so update your verifier before rotating if you cannot tolerate a gap.
Errors: 404 PERMISSION_RESOURCE_NOT_FOUND, plus shared errors.
Verify Webhook Subscription
Endpoint: POST /api/v1/webhooks/{id}/verify
Auth: API key (X-API-Key), project-scoped, write permission.
Re-sends the verification challenge for a subscription stuck in pending_verification.
Response: 200 either way:
- Success:
{ "verified": true, "status": "active", "message": "Subscription verified and activated" } - Failure:
{ "verified": false, "status": "pending_verification", "message": "Verification failed. Ensure your endpoint responds with the challenge value in the JSON body." }
Errors: 400 VALIDATION_BAD_REQUEST when the subscription is not in pending_verification state or the URL is SSRF-blocked, 409 CONFLICT when the subscription was modified while the challenge was in flight, 404 PERMISSION_RESOURCE_NOT_FOUND, plus shared errors.
Send Test Event
Endpoint: POST /api/v1/webhooks/{id}/test
Auth: API key (X-API-Key), project-scoped, write permission.
Sends a signed webhook.test CloudEvent to the subscription URL (respecting its payload_mode), with the standard delivery headers, a 15 second timeout, and the SSRF checks applied.
Response: 200 with the delivery outcome; a failed delivery is still a 200 from this API:
{
"success": true,
"event_id": "evt_9f2c...",
"response_status": 200,
"response_time_ms": 143,
"error": null
}success mirrors whether your endpoint returned 2xx. On failure, error carries HTTP <status>: <statusText> or the transport error message, and response_status may be null.
Errors: 400 VALIDATION_BAD_REQUEST when the subscription is not active or the URL is SSRF-blocked, 404 PERMISSION_RESOURCE_NOT_FOUND, plus shared errors.
Bouncer (KYA-OS Governance) APIs
The Bouncer API powers Vouched KYA's Govern features: delegations, proofs, OAuth, tool configuration, and consent.
Authorization
Endpoint: GET or POST /api/v1/bouncer/authorize
Auth: GET: none; it's the user-facing consent link the user clicks, with parameters in the
query string. POST: API key (X-API-Key), read permission; same parameters in the body for
server-side callers.
Initiates the delegation authorization flow for an AI agent. Both return an authorization_url (or consent_url for credential and consent-only providers) to send the user to.
Request: GET passes these as query parameters, POST as a JSON body. Required: agent_did
and requested_scopes (1 to 20 scopes: comma-separated in the query string, an array in the
body). Optional: agent_name, expires_in_days (1 to 365, default 7), session_id,
worker_url, metadata, provider (explicit provider id), and tool_name (infer the provider
from the tool's authorization requirement). A project is also required: from the API key on
POST, or a project_id parameter (UUID or friendlyId) on the public GET.
Response: 200 with data discriminated by provider_type:
{
"success": true,
"data": {
"provider_type": "oauth2",
"authorization_url": "https://github.com/login/oauth/authorize?...",
"expires_at": "2026-07-27T12:10:00.000Z",
"project_id": "a1b2c3d4-...",
"agent_did": "did:key:z6Mk...",
"requested_scopes": ["cart:read"]
}
}provider_type: "oauth2" carries authorization_url. provider_type: "password" (credential
providers) carries consent_url, provider_name, and a credential_config object for the login
form. provider_type: "none" (consent-only) carries consent_url. Every variant includes
expires_at (the URL expires in 10 minutes), project_id, agent_did, and requested_scopes.
Errors: 400 validation_error for a malformed request (missing agent_did /
requested_scopes), 400 no_project when no project can be resolved, 400 not_configured when
Bouncer is not configured for the project, 400 invalid_provider_config /
invalid_credential_config for an incomplete provider setup (all lowercase Bouncer codes), 429
on the public GET, which is rate-limited before parsing.
Delegations
There is no list endpoint here: browse delegations in the dashboard's Delegations page. Revocation is the DELETE route; notify only records delegations created out-of-band. See Managing Delegations for usage examples. Every endpoint except status polling is documented in full below.
Status polling answers 404 for every request id today. The delegation-request store has
not been built: the route's lookup returns "no such request" unconditionally, so
404 DELEGATION_REQUEST_NOT_FOUND is the only answer a well-formed request id can get. That is
deliberate, not a gap. The endpoint is public and its answer is what an agent uses to decide
whether it may act, so it must not manufacture one; it previously returned a pending status
plus an authorization URL for any well-formed UUID, including ids that had never been issued.
Do not build against the success shape yet.
The response type still declares the four status variants the flow will serve once the store
exists, and they are what a 200 will carry: { status: "pending", authUrl, expiresAt },
{ status: "completed", delegationJwt }, { status: "expired", errorMessage }, and
{ status: "error", errorMessage }, inside { success, data, metadata: { timestamp } }.
Other errors: a non-UUID request id returns 400 INVALID_REQUEST_ID, and an unexpected failure
returns 500 INTERNAL_ERROR.
Create Delegation
Endpoint: POST /api/v1/bouncer/delegations
Auth: API key (X-API-Key), write permission.
Creates a delegation and mints a delegation_token: a W3C VC-JWT signed with EdDSA (Ed25519) by
the project's org DID, carrying a revocation entry on the org's status list. KYA-OS servers verify
it against the org DID document and that status list, without a database lookup.
Request:
{
"agent_did": "did:key:z6Mk...",
"agent_name": "Shopping Assistant",
"user_did": "did:key:z6Mk...",
"user_identifier": "user@example.com",
"scopes": ["cart:read", "cart:write"],
"expires_in_days": 7
}agent_did and at least one scope are required. Optional: user_did (alias issuer_did),
user_id, user_identifier, constraints (not_before, not_after, max_calls,
allowed_origins, ip_whitelist), expires_in_days (1 to 365), metadata (KYA-OS
custom_fields are merged into it), and credential_jwt.
Response: 201 with a Location header pointing at the delegation:
{
"success": true,
"data": {
"delegation_id": "a1b2c3d4-...",
"agent_did": "did:key:z6Mk...",
"user_did": "did:key:z6Mk...",
"scopes": ["cart:read", "cart:write"],
"status": "active",
"issued_at": "2026-07-27T12:00:00.000Z",
"expires_at": "2026-08-03T12:00:00.000Z",
"created_at": "2026-07-27T12:00:00.000Z",
"delegation_token": "eyJhbGciOiJFZERTQSJ9...",
"token_type": "Bearer",
"token_format": "vc+jwt",
"expires_in": 604800
}
}Additional fields may be present (user_identifier, authorization, provenance).
Errors: 400 validation_error for a body that fails the schema, 400 no_project when the
API key has no associated project (lowercase Bouncer codes), 401 for a missing or invalid API
key.
Revoke Delegation
Endpoint: DELETE /api/v1/bouncer/delegations/{delegationId}
Auth: API key (X-API-Key), write permission.
Request: optional JSON body { "reason": "..." } (max 500 characters); an empty body is
accepted.
Response: 200:
{
"success": true,
"data": {
"delegation_id": "a1b2c3d4-...",
"status": "revoked",
"revoked_at": "2026-07-27T12:00:00.000Z",
"was_already_revoked": false
}
}Revocation is idempotent: revoking an already-revoked delegation succeeds with
was_already_revoked: true. reason, agent_did, and user_did may also be present.
Errors: 400 validation_error / no_project (lowercase Bouncer codes), 404 for an
unidentified delegationId.
Get Delegation Tokens
Endpoint: GET /api/v1/bouncer/delegations/{delegationId}/tokens
Auth: Authorization: Bearer <delegation_token>: the VC-JWT itself, not an API key. The
token's sub claim must match {delegationId} and its aud claim names the project.
Request: no body or query parameters.
Response: 200 with the decrypted OAuth tokens stored on the delegation:
{
"success": true,
"data": {
"oauth_access_token": "gho_...",
"oauth_refresh_token": null,
"oauth_expires_at": null,
"oauth_expires_in": null,
"oauth_token_type": "Bearer",
"oauth_scope": "repo read:user"
}
}Responses are never cached (Cache-Control: no-store); tokens are decrypted on demand.
Errors: 401 invalid_token for a missing, malformed, mismatched, or expired delegation
token (its own error code, distinct from the API-key AUTH_* codes used elsewhere on this
page), 404 tokens_not_found when the delegation is inactive, revoked, expired, or holds no
stored OAuth tokens (including stored tokens that have themselves expired), 500 decryption_error when the stored tokens cannot be decrypted.
Verify Delegation
Endpoint: POST /api/v1/bouncer/delegations/verify
Auth: API key (X-API-Key), read permission.
Request:
{
"agent_did": "did:key:z6Mk...",
"delegation_token": "eyJhbGciOiJFZERTQSJ9...",
"scopes": ["cart:read"]
}agent_did is required. Optional: user_did, credential_jwt, delegation_token (stateless
verification), session_id (anchors grant read-back to a durable session link), scopes,
timestamp, and client_info. The grant constraints see the reported client_info.ip_address
only; the server never fills it in from the request, so an ip_whitelist grant without it fails
with client_ip_required. client_info.origin falls back to the Origin header when omitted.
Response: 200 for any well-formed request; the verdict is inside data:
{
"success": true,
"data": {
"valid": true,
"delegation_id": "a1b2c3d4-...",
"credential": { "scopes": ["cart:read"] }
}
}When valid is false, data.error carries { code, message } instead of credential.
credential is the delegation credential detail; additional fields may be present. With a
delegation_token, its user fields are the ones that credential asserts. Without one, the
answer carries only what the request already holds: user_did is the one the request sent, or
else the grant's user DID, and the grant's email, user id and stored credential are never
returned. A grant that names its user by no DID (only an email or OAuth subject) is refused
with user_did_required unless the request names the user, and with user_mismatch when it
carries an application user id or a DID identifier and neither is the requested user_did.
Errors: 400 validation_error / no_project (lowercase Bouncer codes), 401 for a missing
or invalid API key. A failed verification is not an HTTP error: it comes back 200 with
data.valid: false.
Notify Delegation
Endpoint: POST /api/v1/bouncer/delegations/notify
Auth: API key (X-API-Key), write permission.
Audit-trail upsert from KYA-OS after a direct-mode delegation. Idempotent: repeating the same
delegation_id updates the existing record.
Request:
{
"delegation_id": "a1b2c3d4-...",
"agent_did": "did:key:z6Mk...",
"user_did": "did:key:z6Mk...",
"scopes": ["cart:read"],
"provider": "github",
"project_id": "mcp-i-ieu0ro",
"created_at": "2026-07-27T12:00:00.000Z"
}Required: delegation_id (UUID), agent_did, scopes (1 to 50), provider, project_id
(UUID or friendlyId), created_at (ISO 8601). Optional: agent_name, user_did, user_id,
user_identifier, expires_at, metadata. Scopes outside the legacy resource:action shape
are preserved in metadata rather than rejected.
Response: 201 with { delegation_id, status: "recorded", message } for a new record,
200 with status: "merged" when an existing record was updated.
Errors: 400 validation_error, 404 project_not_found, 403 project_mismatch when the API
key can't write to the project in the body (lowercase Bouncer codes). A project-scoped key writes
only to its own project. A key with no project writes only to a project where its owner has write
access.
OAuth
See OAuth Integration for the full flow.
These four browser endpoints run one transaction end to end. Authorization
returns an authorization_url pointing at oauth/start?intent=...; the browser follows it and
is redirected to the consent page with a bound transaction id; the consent page reads the
transaction back from oauth/start?state=... to render the grant, then approves it with
POST oauth/start to get the provider's URL; the provider redirects to oauth/callback, which
mints the delegation and hands the browser a ticket; the success page redeems that ticket at
oauth/result. Every step is bound to a correlation cookie set on the first hop, and every id
is single-use. All four send Cache-Control: no-store, max-age=0 and Referrer-Policy: no-referrer.
The callback is not a JSON API and has no success body: it is the provider's browser redirect
target. Its state is an opaque server-stored transaction id bound to that browser, not an
encoded payload, and reading it consumes it. On success it answers 307 to
/bouncer/consent/success?oauth_result=<ticket>. Three failures also answer 307, to
/bouncer/consent/error with error=access_denied (the provider reported the user declined),
error=token_exchange_failed (the provider rejected the code exchange), or
error=invalid_token_response (the provider returned no access token).
Errors: the callback returns JSON for three cases only: 400 invalid_state for a missing
code and error, a repeated state or code parameter, a state that is unknown, expired,
or not this browser's, a project with no Bouncer config, or a code exchange that could not be
built; 429 rate_limit_exceeded (strict tier, applied before anything is parsed); and
503 oauth_unavailable for any other failure. The token endpoint's errors are listed on its
block below.
OAuth Start
Endpoint: GET or POST /api/v1/bouncer/oauth/start
Auth: none. Both methods authenticate the browser rather than a caller: the transaction id
in the request must exist, must not have been used, and must match the correlation cookie set on
the first hop. POST additionally requires an Origin header matching the request's own origin.
GET does one of two jobs, chosen by which parameter is present, and rejects a request that
carries both or neither:
?intent=<id>opens the transaction. The id comes from theauthorization_urlthat Authorization returned. The response is a303to/bouncer/consent?oauth_transaction=<id>and sets the correlation cookie. There is no body.?state=<id>reads the transaction back, using the id from that redirect, so the consent page can render what is being granted. The response is200.
Response (GET ?state=): note the camelCase field names, unlike the snake_case used by the
rest of the Bouncer family:
{
"success": true,
"data": {
"projectId": "a1b2c3d4-...",
"agentDid": "did:key:z6Mk...",
"agentName": "Shopping Assistant",
"requestedScopes": ["cart:read"],
"expiresInDays": 7,
"providerName": "github"
}
}Request (POST): { "state": "<id>" }, the same id. This is the user's approval: it
consumes the transaction and mints the provider's authorization URL.
Response (POST): 200:
{
"success": true,
"data": {
"authorization_url": "https://github.com/login/oauth/authorize?..."
}
}Errors: 400 invalid_transaction for every rejected request, whichever method and parameter
it used: both or neither parameter on GET, a non-string state or a missing or cross-origin
Origin on POST, an id that is unknown, expired, already consumed, or not this browser's, and a
project with no Bouncer config. 429 rate_limit_exceeded when rate-limited (standard tier on
GET, strict on POST), and 503 oauth_unavailable on an unexpected failure. Both codes ship
the same message, Restart authorization from the requesting agent., and deliberately say no
more than that.
OAuth Result
Endpoint: GET /api/v1/bouncer/oauth/result
Auth: none; the ticket query parameter plus the correlation cookie. The ticket is
single-use and short-lived (two minutes), and no credential ever travels in a URL.
Request: ?ticket=<id>, taken from the oauth_result parameter on the consent success
redirect.
Response: 200. Field names are camelCase here too:
{
"success": true,
"data": {
"delegationId": "a1b2c3d4-...",
"agentDid": "did:key:z6Mk...",
"delegationToken": "eyJhbGciOiJFZERTQSJ9...",
"sessionId": "sess_abc"
}
}sessionId is present only when the authorization carried one.
Errors: uncoded, and the only endpoint on this page whose failures carry no code or message.
The body is { "success": false } and the status is the whole signal: 400 when the ticket is
missing, malformed, unknown, expired, already redeemed, or not this browser's, and 503 on an
unexpected failure. Retrying a 400 will not help; the ticket is gone either way.
Identity
Endpoint: POST /api/v1/bouncer/identity/resolve
Auth: API key (X-API-Key), write permission.
Resolves an OAuth identity (provider + subject) to a persistent user DID. Called by KYA-OS servers during OAuth flows.
Request:
{
"project_id": "mcp-i-ieu0ro",
"oauth_result": {
"provider": "google",
"sub": "1234567890",
"email": "user@example.com",
"email_verified": true,
"name": "Ada Lovelace"
}
}Exactly one of oauth_result or credential_result must be present (never both).
credential_result carries provider, user_id, and optional email / name. project_id
accepts a UUID or friendlyId and must match the API key's project.
Response: 201 when a new account was created, 200 for an existing one:
{
"success": true,
"data": {
"user_did": "did:key:z6Mk...",
"user_account_id": "b1c2d3e4-...",
"is_new_account": false,
"auto_linked": false
}
}Errors: 409 duplicate_identity when the identity is already linked to an account outside this project. Nothing is stored: no account and no link. A sign-in that a concurrent sign-in in the same project overtook resolves to the account that one made (200, is_new_account: false).
Errors: 400 for a malformed body or an API key with no associated project, 404 project_not_found when project_id doesn't resolve, 403 project_mismatch when the API key
isn't scoped to the resolved project. An identity that matches nothing is not an error: a new
account (and DID) is created for it.
Proofs
Endpoint: POST /api/v1/bouncer/proofs
Auth: API key (X-API-Key), write permission.
Submit KYA-OS cryptographic proofs for verification: signatures are validated, nonces checked, and accepted proofs stored. See Proof Verification.
Request:
{
"session_id": "sess_abc",
"delegation_id": "a1b2c3d4-...",
"proofs": [
{
"jws": "eyJhbGciOiJFZERTQSJ9..signature",
"meta": {
"did": "did:key:z6Mk...",
"kid": "did:key:z6Mk...#key-1",
"ts": 1690000000,
"nonce": "unique-session-nonce",
"audience": "https://kya.vouched.id",
"sessionId": "sess_abc",
"requestHash": "sha256:<64 hex>",
"responseHash": "sha256:<64 hex>"
}
}
]
}1 to 100 proofs per batch. Each proof is a detached JWS over the KYA-OS proof meta;
meta.scopeId and meta.delegationRef are optional. delegation_id is optional and nullable.
Optional top-level fields: correlation_id, and a context object (toolCalls,
consentEvents, mcpServerUrl) for dashboard enrichment.
Response: 200 when at least one proof was accepted:
{
"success": true,
"data": {
"accepted": 1,
"rejected": 0,
"outcomes": { "success": 1 }
}
}outcomes counts proofs per outcome (success, failed, blocked, error); a rejected batch
also carries errors[] entries of { proof_index, error: { code, message } }. When every proof
is rejected the endpoint returns 400 all_proofs_rejected with the counts in error.details.
CRISP proof budgets are unsupported because proofs provide no authenticated spend delta or
accounting window. A non-null constraints.crisp_budget on the requested or session-linked
delegation prevents proof acceptance with crisp_budget_unsupported. Remove the constraint
before submitting proofs. Delegation creation rejects this key instead of dropping it.
Project configuration budgets remain advisory and do not authorize proof work.
Errors: 400 validation_error / no_proofs / batch_too_large / proof_validation_error /
all_proofs_rejected for malformed or rejected submissions, 400 no_project when the API key
has no associated project, 404 delegation_not_found / session_not_found when the referenced
delegation or session can't be found (all lowercase Bouncer codes).
Sessions
Endpoint: GET or POST /api/v1/bouncer/sessions
Auth: API key (X-API-Key): read permission for GET, write permission for POST.
POST registers a session during the KYA-OS handshake so the dashboard can show which MCP clients (Claude Desktop, Cursor, MCP Inspector) are connecting. GET looks up a session by session_id for diagnostics.
Request (POST):
{
"session_id": "b64url-anchor-of-22-plus-chars",
"agent_did": "did:key:z6Mk...",
"project_id": "mcp-i-ieu0ro",
"created_at": 1690000000000,
"client_info": { "name": "Claude Desktop", "version": "1.0.0" },
"ttl_minutes": 30
}session_id, agent_did, project_id (UUID or friendlyId), created_at (Unix ms), and
client_info.name are required; client_info also accepts version, protocol_version,
platform, vendor. Optional: client_identity (did, source, registered), server_did,
ttl_minutes (default 30, max 1440), and a challenge object used by enforcement PEPs to anchor
a step-up delegation challenge (when challenge is present, session_id must be at least 22
characters).
Response (POST): 201 for a new session, 200 for an idempotent repeat:
{
"success": true,
"data": {
"session_id": "b64url-anchor-of-22-plus-chars",
"registered": true,
"created_at": "2026-07-27T12:00:00.000Z"
}
}When the request carried challenge, data.challenge returns the server-issued consent_uri,
the org-signed challenge_proof, required_scopes, and issued_at.
Request (GET): query parameter session_id. The response is { success, data: { session } }
with the stored record (id, projectId, agentDid, clientName, clientVersion,
clientDid, registeredAt, createdAt, lastSeenAt). Without session_id the endpoint
returns a readiness message only.
Errors: 401 for a missing/invalid API key, 403 when the API key isn't scoped to the
session's project, 404 for an unidentified session_id (codes are lowercase: unauthorized,
forbidden, project_not_found, not_found), 503 authorization_host_unavailable when the
project's configured consent host can't serve the challenge registration.
Native HTTP
The KYA-OS native HTTP profile, for standalone authorization hosts. A managed deployment's worker delegates to the organization authorization service instead, so a managed deployment's key is refused on all three. A standalone authorization host asserts facts it has already verified (a human logged in, a pickup proof held), and Vouched KYA re-binds each one to its own immutable anchor, the project's active account, and the exact grant before it signs anything. The three operations share a single handler, so the contract below holds for all three.
Auth is stricter than an ordinary API key. Beyond write permission, the key must be the
one bound to the project's active standalone KYA-OS deployment: an ordinary project key, or a
managed deployment's key, resolves and is then refused. Requests are not logged.
Every request: Content-Type: application/json, a body of at most 64 KiB, and a body that
parses and matches the operation's schema. Each schema is strict, so an unrecognized field is
a rejection. Every response carries Cache-Control: no-store.
Two error shapes. Protocol failures are a bare body with the code at error, no success
field and no message:
{ "error": "kyaos/profile-violation" }Authentication and permission failures happen before the handler runs and use the standard error envelope instead:
{
"success": false,
"error": {
"code": "PERMISSION_INSUFFICIENT",
"message": "Insufficient permissions for this operation"
},
"metadata": {
"requestId": "req_abc123",
"timestamp": "2026-07-27T12:00:00.000Z"
}
}So: 401 AUTH_MISSING_CREDENTIALS / AUTH_INVALID_API_KEY / AUTH_EXPIRED_API_KEY and
403 PERMISSION_INSUFFICIENT arrive enveloped; everything below arrives bare. All
kyaos/* codes and their statuses are on the Error Codes page.
Errors shared by all three: 403 kyaos/issuer-forbidden when the key is not this project's
registered native issuer, or is a managed deployment's; 415 kyaos/profile-violation for a non-JSON content type,
408 kyaos/profile-violation for a body that does not arrive in time,
413 kyaos/profile-violation for a body over 64 KiB, and 400 kyaos/profile-violation for
unparseable JSON or a body that fails the schema; and 503 kyaos/authorization-host-unavailable
for any other failure, which is also what a failure inside Vouched KYA's own signing path reports.
The delegation operation answers 403 kyaos/issuer-forbidden before reading a body.
Native HTTP Challenge
Endpoint: POST /api/v1/bouncer/native-http/challenge
Retrieves the org-signed challenge for a session the enforcement PEP already registered. This operation never originates a challenge: the session and its challenge must already exist, and the submitted registration must match the stored one exactly. Only the separately authenticated PEP can create that record, through Sessions.
Request: the session registration, wrapped:
{
"registration": {
"session_id": "b64url-anchor-of-22-plus-chars",
"agent_did": "did:key:z6Mk...",
"project_id": "mcp-i-ieu0ro",
"created_at": 1690000000000,
"client_info": { "name": "Claude Desktop", "version": "1.0.0" },
"challenge": { "http": { "...": "the http challenge the PEP registered" } }
}
}registration is exactly the Sessions POST body and must carry a challenge
with an http payload naming a policy revision.
Response: 200:
{
"success": true,
"data": {
"session_id": "b64url-anchor-of-22-plus-chars",
"registered": true,
"created_at": "2026-07-27T12:00:00.000Z",
"challenge": {
"consent_uri": "https://consent.example.com/consent?sid=...",
"challenge_proof": { "...": "detached org-signed proof" },
"required_scopes": ["cart:read"],
"issued_at": 1690000000000,
"http": { "...": "the stored http challenge payload" }
}
},
"metadata": { "request_id": "req_abc123", "timestamp": "2026-07-27T12:00:00.000Z" }
}Errors: 403 kyaos/issuer-forbidden when project_id is not the caller's project;
400 kyaos/profile-violation when the registration carries no http challenge or no readable
policy revision; 404 kyaos/invalid-session when no such session exists for this project, the
session has expired, or its challenge is older than 10 minutes;
409 kyaos/session-conflict when the stored session or challenge differs in any field from the
submitted registration, including its consent_uri and its http challenge payload.
Native HTTP Delegation
Endpoint: POST /api/v1/bouncer/native-http/delegation
Refuses every caller. Delegation credentials are minted by the organization authorization service after the human has consented, never on a deployment's request.
Errors: 403 kyaos/issuer-forbidden for every authenticated caller. The body is not read.
Native HTTP Propagation Proof
Endpoint: POST /api/v1/bouncer/native-http/propagation-proof
Issues a short-lived, audience-bound proof that an existing delegation still holds, for the resource the session's challenge named. The whole chain is re-verified on every call: the grant, its session, the account, the deployed policy revision, the credential's signature, and its status-list entry.
Request:
{ "delegation_id": "a1b2c3d4-..." }Response: 200:
{
"success": true,
"data": {
"proof": "eyJhbGciOiJFZERTQSJ9...",
"expires_at": 1690000060
}
}proof is a compact JWS (typ: kya-http-propagation+jwt) bound to the resource host and the
holder DID. expires_at is Unix seconds and is at most 60 seconds out, or the delegation's own
expiry if that is sooner.
Errors: 404 kyaos/invalid-session when no such delegation exists for this project;
403 kyaos/chain-broken when the grant, session, policy blob, credential, or status entry does
not line up; 403 kyaos/delegation-revoked when the grant is not active;
410 kyaos/expired when the grant has expired or no proof lifetime is left;
403 kyaos/issuer-forbidden when the grant's account is not active in this project;
403 kyaos/profile-violation when the challenge's resource URL is not a plain https origin;
409 kyaos/session-mismatch when the deployed policy no longer matches the revision the session
was challenged under; 403 kyaos/scope-insufficient when the grant carries a scope the
challenge did not require; 403 kyaos/holder-mismatch when the holder does not match the grant;
403 kyaos/invalid-signature when the credential does not verify;
503 kyaos/policy-unavailable when engine enforcement is off or no policy is deployed.
Project Configuration
See Tool Protection and Consent Flows for usage. In the dashboard, per-tool protection and consent settings are managed at Policy → Auth; the tool list there (card 02) fills itself, shows each tool's declared scopes, and can run discovery and remove a tool. Every endpoint except the legacy global config is documented in full below.
The legacy global config route is deprecated and functional: it requires an agent_did query
parameter, resolves the project from the API key, and responds with X-Deprecated: true and a
Sunset header. Use the project-scoped endpoint instead. Its errors: 400 missing_agent_did /
no_project, 404 config_not_found, 403 agent_denied (lowercase Bouncer codes).
Get or Update Project Config
Endpoint: GET or PUT /api/v1/bouncer/projects/{projectId}/config
Auth: API key (X-API-Key, or Authorization: Bearer) with access to this project.
{projectId} accepts a UUID or friendlyId.
Request: GET: no body or query parameters. PUT: { "config": { ... } } with a partial
KYA-OS server configuration (a bare config object without the config wrapper is also
accepted); the service validates and merges it.
Response: GET returns 200 with { success, data: { config } }: the merged configuration
with tool protections embedded at config.toolProtection.tools (the single source of truth a
KYA-OS MCP server reads; no separate tool-protections call needed). Sensitive fields are masked.
Cached for 60 seconds. PUT returns { success, data: { config, changes } } with the masked
updated config and the list of changes.
Errors: 404 PROJECT_NOT_FOUND / MCPI_CONFIG_NOT_FOUND, 403 PERMISSION_FORBIDDEN when
the key isn't scoped to the project. GET only: 400 CONFIG_VALIDATION_ERROR -- from an
explicit response-schema check when the merged config fails validation for a reason other
than an empty agentDid/serverDid, or from a separate catch that maps any other
Zod-shaped error thrown in the handler to the same code -- and 500 PROJECT_LOOKUP_FAILED /
CONFIG_FETCH_FAILED on other downstream failures. PUT only: 400 INVALID_REQUEST_BODY /
VALIDATION_ERROR on a malformed request, 500 INTERNAL_SERVER_ERROR when the response
fails its own schema, and 500 PROJECT_LOOKUP_FAILED / CONFIG_UPDATE_FAILED on other
downstream failures.
Validate Project Config
Endpoint: POST /api/v1/bouncer/projects/{projectId}/config/validate
Auth: API key (X-API-Key) with access to this project.
Request: { "config": { ... } }, the same partial-config shape as the PUT above. Nothing
is written: this is a dry-run check.
Response: 200 with { success, data: { valid, errors, warnings } }.
Errors: 404 PROJECT_NOT_FOUND / MCPI_CONFIG_NOT_FOUND, 400 INVALID_REQUEST_BODY /
VALIDATION_ERROR, 403 PERMISSION_FORBIDDEN when the key isn't scoped to the project.
Get Consent Config
Endpoint: GET /api/v1/bouncer/projects/{projectId}/consent-config
Auth: API key (X-API-Key) with access to this project.
Request: no body or query parameters.
Response: 200 with { success, data: { config, metadata } } where config is the consent
page configuration (branding, terms, UI settings, custom fields; edit it in the dashboard) and
metadata carries projectId, friendlyId, version, updatedAt, cacheVersion. The
X-Consent-Version header repeats the cache version.
This response is not cacheable. The route asks for public, max-age=60, stale-while-revalidate=30, but the shared v1 response helper sets Cache-Control: no-store, no-cache, must-revalidate on every v1 success response, and that is what ships. Poll it, or
cache it yourself against X-Consent-Version, which does survive.
Errors: 404 PROJECT_NOT_FOUND when {projectId} doesn't resolve (this used to answer
500 INTERNAL_SERVER_ERROR), 404 CONSENT_CONFIG_NOT_FOUND, 403 when the key isn't scoped to
the project, 429 RATE_LIMIT_EXCEEDED when the plan's v1 rate limit is exceeded.
Create Delegation (Consent Flow)
Endpoint: POST /api/v1/bouncer/projects/{projectId}/delegations
Auth: none; part of the browser-based consent flow, where no API key is available. The project must exist.
Same request and response contract as Create Delegation, with three
differences: the project comes from the path ({projectId}, UUID or friendlyId), no API key
is required, and the response data also carries id (an alias of delegation_id).
Errors: 404 project_not_found when {projectId} doesn't resolve, 400 validation_error
for a body that fails the schema (lowercase Bouncer codes).
List Providers
Endpoint: GET /api/v1/bouncer/projects/{projectId}/providers
Auth: API key (X-API-Key) with access to this project.
Request: no body or query parameters. Supports conditional requests: send If-None-Match
with the previous ETag to get 304 Not Modified when the configuration is unchanged.
Response: 200 with a signed provider-configuration document:
{
"success": true,
"data": {
"version": 1,
"source": {
"projectId": "a1b2c3d4-...",
"projectFriendlyId": "mcp-i-ieu0ro",
"generatedAt": "2026-07-27T12:00:00.000Z",
"agentShieldVersion": "x.y.z"
},
"providers": { "github": { "id": "github" } },
"signature": "hmac-hex",
"signedFields": ["version", "providers"],
"configuredProvider": "github"
}
}providers maps provider id to its public configuration (built-in OAuth providers plus any
configured custom and credential providers); per-provider fields vary and additional fields may
be present. The HMAC signature covers signedFields for tamper detection.
configuredProvider is the project's default provider, or the first configured one. Cached for
60 seconds with stale-while-revalidate.
Errors: 404 PROJECT_NOT_FOUND, 403 when the key isn't scoped to the project.
Report Deployment Health
Records a liveness heartbeat for the project's KYA-OS deployment. The response reports only that the heartbeat was accepted; it carries no health state of its own.
Endpoint: POST /api/v1/bouncer/projects/{projectId}/health
Auth: API key (X-API-Key, or Authorization: Bearer) with access to this project.
Request: no body. Send X-Agent-Did to attribute the heartbeat to a specific deployment. When
the header is absent the heartbeat is attributed to the project's oldest active deployment
instead, so a project running several deployments should always send it.
Response: 200 with the v1 success envelope:
{
"success": true,
"data": { "reported": true },
"metadata": {
"requestId": "req_...",
"timestamp": "2026-07-27T12:00:00.000Z",
"version": "v1"
}
}Errors: 404 PROJECT_NOT_FOUND when no project matches the id, and 404 DEPLOYMENT_NOT_FOUND
when the project has no active deployment to attribute the heartbeat to. A DID that matches no
deployment gives DEPLOYMENT_NOT_FOUND rather than falling back to the primary one.
KYA-OS Audit Events
Ingest Audit Events
Batch ingest for the KYA-OS Audit Events format (SPEC-EVENTS v0.1). Customers running the kya-os protocol point their emitter at this one endpoint (KYA_OS_EVENTS_URL + KYA_OS_EVENTS_TOKEN) and Vouched KYA fans the events out server-side into its existing surfaces, replacing hand-integration of the four legacy bouncer ingest endpoints (delegations/notify, sessions, proofs, log-detection), which remain available for existing integrations.
Endpoint: POST /api/v1/kya-os/events (plus OPTIONS for CORS preflight)
Auth: API key (X-API-Key), write permission, project-scoped. Events land only in the API key's own project; the body cannot target another project.
Request:
{
"events": [
{
"type": "tool.invoked",
"tool": { "name": "search_products" },
"verdict": "pass"
}
]
}events must contain 1 to 100 elements. Each event is one of the seven SPEC-EVENTS v0.1 types, discriminated on type: delegation.observed, delegation.minted, delegation.revoked, session.started, agent.verified, tool.invoked, proof.verified. Field names are camelCase on the wire (matching @kya-os/mcp protocol types, not the snake_case of the legacy bouncer endpoints). Validation is deliberately lenient per event: a malformed or unrecognized-type event is skipped and counted, never failing the batch. A tool.invoked event whose ts is more than 5 minutes ahead of the server clock, or more than 14 days old, is skipped with reason event_time_refused: clock_skew or event_time_refused: event_too_old, one whose ts has more than 9 fractional digits is skipped with reason event_time_unreadable, and one whose ts falls below the project's retention floor or inside a fenced partition range is skipped with reason event_below_retention_floor or event_in_fenced_range (nothing is stored), and one whose detection the database refuses for its own values is skipped with reason event_refused_by_database (nothing is stored, and delivering it unchanged fails the same way). Delivering an unchanged tool.invoked event again stores no second detection, because its identity derives from the server DID, session id, ts, tool name and capability, verdict, delegation jti, stages, error excerpt, principal, client user agent and IP, and the session's agent DID and client. proof.verified JWSes are re-verified server-side as defense in depth.
Response: 202 Accepted:
{
"accepted": 42,
"skipped": 1,
"skipped_details": [{ "index": 7, "type": "tool.invoked", "reason": "..." }]
}accepted/skipped sit at the top level (no success envelope); emitters across repos assert on this contract shape. skipped_details entries carry the batch index, the event type when one was readable off the raw payload, and a reason; the list is capped for response size. Events are processed before the response is sent, so the counts are real, and the response carries an X-Request-ID header.
Errors: 400 invalid_json for a non-JSON body, 400 validation_error when the envelope is not { events: [...] } with 1 to 100 elements (these two use lowercase codes, unlike the API-key AUTH_* codes), 401 AUTH_MISSING_CREDENTIALS / AUTH_INVALID_API_KEY / AUTH_EXPIRED_API_KEY, 403 PERMISSION_INSUFFICIENT when the key lacks write permission. Per-event problems never produce a 4xx; they surface in skipped_details.
Read the Operator Revocation Feed
Every delegation an operator revoked in the API key's project, for KYA-OS resource servers to deny locally: revocations from the dashboard, from DELETE /api/v1/bouncer/delegations/{delegationId} and from the management CLI. A revocation a resource server reported itself through POST /api/v1/kya-os/events is not included. The feed is verifier-local state; reading it never changes an issuer's status list.
Endpoint: GET /api/v1/kya-os/revocations?since=<cursor> (plus OPTIONS for CORS preflight)
Auth: API key (X-API-Key or Authorization: Bearer), read permission, project-scoped. The feed is always the key's project.
Response: 200 OK, Cache-Control: private, no-store:
{
"revocations": [
{
"jti": "urn:uuid:0f24d1c2-8e5a-4d3b-9f61-7a2c33b8d901",
"revokedAt": "2026-10-08T12:05:00.000Z",
"reason": "revoked from the Checkpoint dashboard"
},
{ "jti": "3f9c2b7e-6a41-4d8e-9b25-1e7c0a4d5f62", "revokedAt": "2026-10-08T12:07:15.000Z" }
],
"nextCursor": "seq_000000000000000042_7a2baf31",
"hasMore": false
}jtiis the credential handle a verifier matches: the credential'svc.id, else its JWTjti. A grant ingested throughPOST /api/v1/kya-os/eventsappears under thejtiit was reported with; a Vouched KYA-minted credential appears under its delegation id.reasonis omitted when the operator gave none (it is nevernull) and is at most 500 UTF-16 code units.- A page holds at most 1000 entries.
hasMoreistruewhen another page is ready now. nextCursoris opaque and bound to the key's project: pass it back verbatim assinceand never parse it. It is a sequence the producer assigns, not a timestamp, and an entry only becomes visible after every entry before it, so polling withsincenever skips one.nullmeans nothing follows the cursor you sent: ask again with that same cursor (or with none, if you sent none). Omitsinceto read from the start.- Entries are in feed order, which need not be
revokedAtorder.
Errors: 400 invalid_cursor when since is not a cursor this feed issued for the key's project (another format, an empty value, the parameter twice, another project's cursor, or one ahead of the feed): drop the cursor and read from the start. The body is { "success": false, "error": { "code": "invalid_cursor", "message": "..." } }. Also 401 AUTH_MISSING_CREDENTIALS / AUTH_INVALID_API_KEY / AUTH_EXPIRED_API_KEY, and 403 PERMISSION_INSUFFICIENT when the key lacks read permission.
The wire contract is pinned by apps/web/tests/contract/kya-os-revocation-feed.fixture.json, which consumers vendor verbatim.
Submit Audit Ledger Entry
Authoritative KYA-OS Auditability Protocol recorder ingest. Intentionally separate from /api/v1/kya-os/events (which is a compatibility fan-out into operational tables): a successful response here contains the exact signed ledger entry and recorder receipt committed by the @kya-os/mcp v1.11.0 recorder contract.
Endpoint: POST /api/v1/audit/entries (plus OPTIONS for CORS preflight)
Auth: Source-bound audit ingest credential, presented as an x-kya-audit-key header or Authorization: Bearer <credential>. This is the recorder credential provisioned for a ledger source, not a Vouched KYA API key; the credential's project must match both the submission's source and ledger.
Request: an audit recorder submission envelope:
{
"ledgerId": "...",
"expectedLedgerEpochId": "...",
"producerEvent": { "...": "signed producer event" },
"encryptedEvidence": [{ "ref": { "...": "evidence reference" }, "ciphertextBase64url": "..." }]
}expectedLedgerEpochId is optional. Evidence ciphertext must be canonical unpadded base64url, and the total request is capped at 6 MiB (enforced even for chunked bodies without a Content-Length). The full envelope and producer-event schemas live in the @kya-os/mcp audit contract and are not itemized field-by-field here.
Response: 200:
{
"success": true,
"data": {
"schema": "https://schema.kya-os.org/v1/protocol/audit/ingest-response/v1.0.0",
"entry": { "...": "committed signed ledger entry" },
"receipt": { "...": "the entry's recorder receipt" },
"verification": { "...": "verification facts for the committed entry" }
},
"requestId": "req_abc123"
}receipt duplicates entry.recorderReceipt for convenience. Responses are Cache-Control: private, no-store with an X-Request-ID header.
Errors: the body is { success: false, error: { code, message, details? }, requestId }.
Every relayed protocol code carries the AUDIT_ prefix on the wire. The ten that the table
above does not name by status (AUDIT_EVIDENCE_LEGAL_HOLD, AUDIT_EVIDENCE_ACCESS_DENIED, the
four AUDIT_CHECKPOINT_* codes, AUDIT_PROJECTION_CONFLICT, and the three AUDIT_MIRROR_*
codes) fall through to 500. At 500 and 503 the recorder's own message and details are
replaced with Audit recorder is temporarily unavailable; below 500 both are passed through.
The full list, with statuses, is on the Error Codes page.
Gateway APIs
The Gateway API family backs Vouched KYA's MCP gateway: each organization's
OAuth 2.1 authorization server that MCP clients (Cursor, Claude Desktop, VS Code,
ChatGPT) authenticate against, plus the machine endpoints the gateway itself
calls. None of these endpoints take an X-API-Key: each one authenticates by
its flow, the same pattern as the /bouncer/oauth/* exceptions in
Authentication.
The authorization server endpoints sit under the organization's issuer,
https://kya.vouched.id/oauth/{orgSlug}, or https://auth.{domain}/oauth/{orgSlug}
when the organization has a verified custom domain. Each organization has one
issuer; the other host returns 404, as does an unknown organization.
The OAuth endpoints (register, authorize, token) and needs-authorization are rate-limited per client IP. A rate-limited request returns
429 with { "error": "rate_limit_exceeded", "error_description": "Too many requests. Please try again later." }
and X-RateLimit-Limit / X-RateLimit-Remaining (plus X-RateLimit-Reset when
available). The connections callback is the one exception: it responds to a
rate-limited browser with its redirect contract (connection_error=rate_limited)
instead of a raw JSON 429.
Authorization Server Metadata
RFC 8414 metadata for one organization's issuer. MCP clients probe several
discovery URLs for a path-bearing issuer, so the same document is served at
/.well-known/oauth-authorization-server/oauth/{orgSlug},
/.well-known/openid-configuration/oauth/{orgSlug},
/oauth/{orgSlug}/.well-known/oauth-authorization-server and
/oauth/{orgSlug}/.well-known/openid-configuration.
Auth: None, public. Cached for 60 seconds.
Response: 200:
{
"issuer": "https://kya.vouched.id/oauth/acme",
"authorization_endpoint": "https://kya.vouched.id/oauth/acme/authorize",
"token_endpoint": "https://kya.vouched.id/oauth/acme/token",
"registration_endpoint": "https://kya.vouched.id/oauth/acme/register",
"jwks_uri": "https://kya.vouched.id/orgs/acme/jwks.json",
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"],
"token_endpoint_auth_methods_supported": ["none"],
"scopes_supported": ["mcp"],
"client_id_metadata_document_supported": true
}The OpenID-named URLs serve this OAuth document: the server issues no ID tokens.
Errors: 404 for an unknown organization or a host that is not the
organization's issuer host.
Organization Key Set
The organization's signing keys as an RFC 7517 key set: the jwks_uri of its
authorization server metadata. Access tokens carry the kid of the key that
signed them.
Endpoint: GET /orgs/{orgSlug}/jwks.json
Auth: None, public. CORS-enabled; cached for 60 seconds.
Response: 200 with Content-Type: application/jwk-set+json:
{
"keys": [
{
"kty": "OKP",
"crv": "Ed25519",
"x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
"kid": "did:web:kya.vouched.id:orgs:acme#key-1",
"alg": "EdDSA",
"use": "sig"
}
]
}An organization that has not issued a token yet has no key, and the set is empty.
Errors: 404 for an unknown organization or a host that is not the
organization's issuer host.
Register OAuth Client
Dynamic client registration per RFC 7591. Clients that use opaque IDs must
POST their metadata and use the generated client_id for authorization.
A 201 response confirms that Vouched KYA stored the registration and its
redirect allowlist. Authorization and consent requests validate the callback
against this registration. HTTPS Client ID Metadata Document (CIMD) URLs use
the verified document's redirect allowlist instead.
An opaque ID with no stored registration returns 400 invalid_client during
authorization, with no callback redirect. Clients with fixed IDs or older cached
registrations must register again. See the
re-registration instructions.
Endpoint: POST /oauth/{orgSlug}/register
Auth: None, public. Rate-limited per client IP.
Request:
JSON body, validated in the handler (no shared Zod schema):
Response: 201 with Cache-Control: no-store:
{
"client_id": "d3b1a6a0-1234-4c1e-9f6a-abcdef012345",
"client_id_issued_at": 1753617600,
"client_name": "Cursor",
"redirect_uris": ["cursor://anysphere.cursor-mcp/oauth/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "none",
"scope": "mcp"
}software_id and software_version are echoed back when they were accepted.
Errors: 400 invalid_redirect_uri for a missing, empty, or disallowed
redirect_uris entry; 400 invalid_client_metadata for a non-JSON body, a
token_endpoint_auth_method other than none, an unsupported grant or
response type, or an over-long client_name; 429 rate_limit_exceeded;
500 server_error if registration cannot be persisted or the generated
client_id collides with the CIMD client-id shape (a defensive guard). Errors use the
RFC 6749 shape { error, error_description }.
Authorize
OAuth 2.1 authorization endpoint. The target organization is the issuer's, so
an MCP client always gets a token for the organization it asked for. Validates
the params, binds redirect_uri to the registered client, resolves the
resource, and redirects the browser to the consent page, which mints the
authorization code.
Endpoint: GET /oauth/{orgSlug}/authorize
Auth: Depends on the org's gateway consent config. Default mode requires a
signed-in dashboard session plus membership in {orgSlug}; an unauthenticated
browser is redirected to /signin with a callbackUrl back to this endpoint.
Orgs configured for merchant credential mode skip both gates: the consent page
handles merchant sign-in via the org's configured credential provider.
Rate-limited per client IP.
Request:
Query parameters:
Response: a redirect to the consent page, /consent/{requestId}. The
request id names a server-side consent request that holds the client,
redirect URI, state, PKCE challenge, scopes, resource and issuer, so the page
URL carries none of them. Unauthenticated browsers on the session path are
redirected to /signin. Per RFC 6749 §4.1.2.1, most validation failures
redirect to redirect_uri with error, error_description, and state
query parameters.
Errors: 404 for an unknown organization or a host that is not the
organization's issuer host. Before the client and its callback are trusted,
an error is answered with the organization's branded HTML page, never a
redirect to the callback: 400 "Reconnect this app" for an unknown opaque ID
(remove the connector and add it again), 400 for an unresolved CIMD
document, an unregistered callback, a missing or disallowed redirect_uri,
missing client_id or response_type, or a resource the organization does
not register (exactly one is required); 503 for a temporary registration
lookup outage. Retry a 503 without clearing the registration. The page names
the organization only, never the client. Loopback callbacks can
vary their port and loopback host spelling. Their scheme, path, and query must
match. Error redirects carry invalid_request (missing state /
code_challenge, or a code_challenge_method other than S256),
unsupported_response_type, or invalid_scope, and access_denied when the
signed-in user is not a member of the org. 429 rate_limit_exceeded as JSON.
Consent Policy
The project's consent policy as a client needs to render and pre-check it: the scopes consent may grant, the longest a grant may last, and each authored capability's default and risk.
Endpoint: GET /api/v1/kya-os/consent-policy
Auth: project API key (Authorization: Bearer <key>) with read
permission. A key only ever sees its own project's policy. A missing or invalid
key returns 401 JSON.
Response: 200 with Content-Type: application/json, ETag: "<etag>" and
Cache-Control: private, no-cache.
{
"allowedScopes": ["mcp", "records:clinical", "records:read"],
"maxGrantSeconds": 2592000,
"capabilities": [
{ "scope": "records:read", "defaultOn": true, "riskLevel": "low" },
{ "scope": "records:clinical", "defaultOn": false, "riskLevel": "high" }
],
"etag": "71f3088097857b66bd26818dc50778eb5f6ff8615740cd5e32fee4447729c79d"
}riskLevel is one of low, medium, high or critical. maxGrantSeconds
is present only when the project stores a consent policy. The body etag is
the bare SHA-256 hex; the ETag header carries the same value as a quoted
strong validator ("<etag>"), never a weak one. The hash covers the canonical
JSON of the body without etag plus the active preset of every scope that has
presets, so the same policy always gives the same ETag and switching a preset
always changes it.
Send If-None-Match: "<etag>": when it matches, the response is 304 with the
same ETag header and no body.
A scope's policy can be one policy or named presets with an active one. Switching the active preset applies to consent requests created or rendered afterwards; delegations already granted are not changed or revoked.
Token
OAuth 2.1 token endpoint. Exchanges an authorization code for a KYA-OS
Delegation VC-JWT access token plus a refresh token, or rotates a refresh
token. Access tokens are signed with the issuing org's own key and are only
minted while the underlying delegation is active.
Endpoint: POST /oauth/{orgSlug}/token
Auth: None (public clients). The request authenticates with the single-use
authorization code plus the PKCE code_verifier, or with the refresh token.
Rate-limited per client IP.
Request:
Body must be application/x-www-form-urlencoded.
grant_type=authorization_code:
grant_type=refresh_token:
Response: 200 with Cache-Control: no-store:
{
"access_token": "eyJhbGciOiJFZERTQSIs...",
"token_type": "Bearer",
"expires_in": 900,
"refresh_token": "N2Y4...base64url...",
"scope": "mcp"
}access_token is a W3C Verifiable Credential in JWT form and expires after
15 minutes, or at the delegation's expiry if that is sooner; expires_in gives
the actual lifetime. Every grant returns a fresh refresh_token that expires
after 30 days or at the delegation's expiry, whichever is sooner; the previous
refresh token is invalidated, and replaying an already-used refresh token
revokes every outstanding token on its delegation.
Errors: 400 invalid_request for a non-form body, a missing required
parameter, or a code_verifier outside 43 to 128 characters;
400 unsupported_grant_type for any grant_type other than the two above;
400 invalid_grant for a code that is invalid, expired, or already used, a
code or refresh token issued by another organization's authorization server, a
client_id or redirect_uri mismatch, a failed PKCE check, a refresh token
that is invalid, expired, or revoked, a delegation that is no longer active,
or a delegation that has expired (Delegation has expired; the refresh grant
also revokes every outstanding refresh token on it); 429 rate_limit_exceeded; 500 server_error when the delegation
row is missing, the issuing org is missing, deleted, or has an invalid slug,
or minting fails (the one-time code or refresh-token claim is rolled back so
the client can retry). Errors use the RFC 6749 shape
{ error, error_description }.
Needs-Authorization Challenge
Public discovery endpoint serving the org-signed needs_authorization consent
challenge that the RFC 9728 resource metadata's kyaos_needs_authorization
extension points at. A KYA-OS-aware client fetches the challenge here and
verifies the proof against the org's did:web.
Endpoint: GET /api/v1/gateway/oauth/needs-authorization
Auth: None, public. The accountable operator is resolved server-side from the project owner and is deliberately not accepted from the request.
Request:
Query parameters:
Response: 200 with Cache-Control: no-store and a body of
{ challenge, content, proof }, where content is exactly the material the
challenge's response hash binds. The challenge's authorizationUrl is always the
organization's authorization endpoint (/oauth/{orgSlug}/authorize), whether or
not the request names an agent. The inner shapes come from the producer
service and are not itemized here.
Errors: 400 invalid_request for a missing project_id, an empty scope
list; 404 unknown_resource when no org resolves for the project;
429 rate_limit_exceeded when one client IP sends more than 100 requests a
minute, checked before the request is validated; 500 server_error on a
producer failure. Errors use the RFC 6749 shape { error, error_description }.
Organization Status Lists
Every organization publishes its own revocation lists, signed with its own key
(the key /orgs/{slug}/did.json publishes). A credential's
credentialStatus.statusListCredential names the list and
credentialStatus.statusListIndex the bit: 0 = valid, 1 = revoked. A list holds
131,072 bits; a full list is followed by a new one with a new listId. A
revocation bit is final.
One list, two envelopes, the same bits:
Auth: None, public.
Response: 200 with Cache-Control: public, max-age=60 and an ETag;
If-None-Match with the current tag answers 304.
{
"@context": ["https://www.w3.org/2018/credentials/v1", "https://w3id.org/vc/status-list/2021/v1"],
"id": "https://kya.vouched.id/orgs/acme/status-lists/7f1c2a9e-4b3d-4e5f-8a6b-1c2d3e4f5a6b",
"type": ["VerifiableCredential", "StatusList2021Credential"],
"issuer": "did:web:kya.vouched.id:orgs:acme",
"issuanceDate": "2026-10-08T22:53:00Z",
"expirationDate": "2026-10-08T22:58:00Z",
"credentialSubject": {
"id": "https://kya.vouched.id/orgs/acme/status-lists/7f1c2a9e-4b3d-4e5f-8a6b-1c2d3e4f5a6b#list",
"type": "StatusList2021",
"statusPurpose": "revocation",
"encodedList": "uH4sIAAAAAAAA..."
},
"proof": { "type": "JwtProof2020", "jwt": "eyJhbGciOiJFZERTQSIs..." }
}proof.jwt is an EdDSA JWS (kid = the org key in its DID document) over
{ iss, sub, iat, exp, vc }, where vc is the credential above, exactly. Check
the signature against the org's DID document and read the bit from the signed
vc, never from the copy beside it; reject the list when the two differ, when
it is past exp (at most 300 seconds after iat), or when anything fails.
encodedList is u + base64url of the GZIP of the bitstring, bit order
most-significant first. @kya-os/checkpoint-shared/mcpi/status-list
(verifyStatusList) does all of this.
Errors: 404 not_found for an unknown organization or a listId that is
not one of its lists; 503 status_list_unavailable (no-store) when the list
cannot be signed. A list is never served unsigned.
Connection Callback
The upstream OAuth provider's redirect target for the dashboard's "Connect" flow (Vouched KYA acting as an OAuth client to providers such as GitHub). Not an endpoint integrations call directly: the provider redirects the user's browser here after the consent step. Validates the single-use CSRF state token, checks that the browser is signed in as the user who started the flow, exchanges the code server-to-server, rejects scope sprawl, stores the encrypted tokens, and sends the browser back where it started.
Endpoint: GET /api/v1/gateway/connections/{provider}/callback
Auth: The dashboard session of the user who started the flow, plus the
single-use state token minted at authorize time. Rate-limited per client IP.
Request: the provider supplies code and state query parameters on
success, or error (with state) when the user denies consent.
Response: always a 307 redirect. On success the original page is
reopened with ?connected={provider}. On failure the redirect carries
?connection_error={reason}&connection_provider={provider} and, when the
provider returned its own error string, connection_provider_error. When the
state cannot be resolved at all, or the browser is not signed in as the user
who started the flow, the fallback target is /dashboard with
connection_error only. The stable reason codes:
Errors: none as HTTP error statuses; every failure is reported through the redirect contract above.
Vault Resolve (Gateway)
Decrypts a user's per-upstream secrets for a gateway tool call. Called by
Vouched KYA's own gateway, not by customer code: the trust anchor is the
project's stored gateway public key and trusted gateway DID, set during
upstream provisioning. Secrets resolve from the user's OAuth connections
first (refreshing near-expiry tokens inline), then fall back to pasted
secrets. Distinct from /api/v1/vault/{projectId}/resolve (Resolve
Secrets), which is a different route with API-key auth.
Endpoint: POST /api/v1/gateway/vault/{projectId}/resolve
Auth: Ed25519 assertion JWT in the body (assertion field), not an API
key. The JWT must be EdDSA-signed by the project's registered gateway key
(or, during a gateway key rotation, by its staged next key),
its iss must equal the project's trusted gateway DID, its projectId claim
must match the route, and its userDid, toolName, and sessionId claims
must match the body copies.
The assertion must also include a nonce. Each nonce is single-use for the verified gateway DID. Create a new assertion for each resolve request. If nonce storage is unavailable, the endpoint refuses the request before reading secrets.
Request:
All fields required (Zod-validated):
{
"assertion": "eyJhbGciOiJFZERTQSIs...",
"envVarNames": ["GITHUB_TOKEN"],
"userDid": "did:web:example.com:users:abc",
"toolName": "create_issue",
"sessionId": "sess_123"
}envVarNames must contain at least one name.
Response: 200 with Cache-Control: no-store:
{
"success": true,
"data": {
"secrets": {
"GITHUB_TOKEN": "gho_..."
},
"_meta": {
"orgSlug": "acme",
"upstreamSlug": "github"
}
}
}A user with no matching secrets gets 200 with an empty secrets map, not a 404. Names that fail to resolve are omitted from secrets. The response is
validated against the shared vaultResolveSuccessSchema wire contract.
Errors: every error path uses the single envelope
{ success: false, error: { code, message, data? } }:
Genuinely unexpected failures surface as 500 INTERNAL_SERVER_ERROR via the
shared error handler.
Vault
Runtime secret resolution for KYA-OS workers. Per-user secrets are stored encrypted and resolved at call time; this endpoint is called by the deployed worker, not by hand-written customer integrations.
Resolve Secrets
Resolves per-user encrypted secrets (environment variable values) for a runtime tool call. Auth is dual-factor: the project API key plus a signed assertion that binds the request to a user, tool, and session. Distinct from the gateway-side Vault Resolve (Gateway), which authenticates with a gateway assertion only.
Endpoint: POST /api/v1/vault/{projectId}/resolve
Auth: API key (X-API-Key) with access to this project, plus an Ed25519 assertion JWT in the body.
The assertion can be signed by any live agent deployment key for the project. Its header must
use alg: "EdDSA" and typ: "JWT". Required claims are projectId, userDid, toolName,
sessionId, exp, and nonce. The projectId must identify the resolved project. The exp
must be unexpired and no more than 300 seconds ahead of the server clock.
Each nonce is single-use for the verified deployment DID. Create a new assertion for each resolve request. If nonce storage is unavailable, the endpoint refuses the request before reading secrets. Requests are limited per API key to 10 per second and 120 per minute, with a burst limit of 100 requests per 10 seconds.
Request:
{
"assertion": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwcm9qZWN0SWQiOiIuLi4ifQ.c2ln",
"envVarNames": ["MY_API_KEY", "OTHER_SECRET"]
}envVarNames must contain at least one name.
Response:
{
"success": true,
"secrets": {
"MY_API_KEY": "decrypted-plaintext-value"
}
}Served with Cache-Control: no-store. A 200 with an empty secrets object means nothing matched: requested names with no stored secret are omitted rather than erroring, as are secrets that fail to decrypt. Every resolve is audit-logged.
Current scoping behavior (this matches the code and is flagged there as an in-progress area): secrets are looked up for the API key owner's user account. The assertion's userDid is required and audit-logged but is not yet mapped to a user for the lookup, and envVarNames is not yet filtered against a per-tool allowlist.
Errors: 401 AUTH_MISSING_CREDENTIALS / AUTH_INVALID_API_KEY / AUTH_EXPIRED_API_KEY for API-key failures, 404 NOT_FOUND when the project does not exist, 403 FORBIDDEN when the API key lacks project access, 400 INVALID_JSON for an unparsable body, 400 VALIDATION_INVALID_REQUEST when the body fails schema validation, 404 NO_AGENT_KEY when no live agent deployment key is available, 400 INVALID_ASSERTION for an invalid JWT header or missing claims, 401 INVALID_SIGNATURE when no live deployment key verifies the signature, 403 ASSERTION_EXPIRED when exp is expired or more than 300 seconds ahead, 403 PROJECT_MISMATCH when the assertion identifies another project, 403 ASSERTION_REPLAYED when the verified deployment already used this nonce, 429 RATE_LIMIT_EXCEEDED when the API key exceeds its limit, and 503 SERVICE_UNAVAILABLE_TRANSIENT when nonce storage is unavailable. Retry a 503 with a new assertion.
Molti (Managed Agent Runtime) APIs
These endpoints are the wire contract between Vouched KYA and a deployed agent's @kya-os/compute process. They are machine-to-machine: the caller is the agent container, not a customer integration.
Two credentials appear here:
- Heartbeat token (
X-Heartbeat-Tokenheader): a per-deployment secret issued at deploy time. Used by managed deployments. - API key (
X-API-Keyheader, orAuthorization: Bearer): the standard project API key. Used by BYOK deployments on the config-bundle endpoint.
Error responses use the base envelope ({ success: false, error: { code, message } } with a metadata block that has no version field).
Agent Heartbeat
Receives a liveness heartbeat from the compute process, updates the agent's status, and returns any pending commands (stop, config refresh).
Endpoint: POST /api/v1/molti/agents/{agentDid}/heartbeat
Auth: X-Heartbeat-Token header: the per-deployment heartbeat token (not an API key). Compared timing-safe against the stored token. A missing token, an invalid token, and an unrecognized agentDid all return the same 401 so deployment existence cannot be probed. Rate limiting is applied after authentication, keyed by agent DID.
Request:
The agentDid path segment is the URL-encoded agent DID. Body (HeartbeatRequestSchema):
{
"agentDid": "did:key:z6Mk...",
"status": "running",
"computeVersion": "1.7.7",
"openclawVersion": "2026.8.1",
"machineId": "d891234f5e6789",
"uptimeSeconds": 3600,
"memoryMb": 256,
"lastUserActivityAt": "2026-08-19T11:42:07.000Z"
}Required fields: agentDid (must match the URL parameter, otherwise 400), status (starting | running | error | stopping), computeVersion. Optional: openclawVersion, machineId, uptimeSeconds, memoryMb, lastUserActivityAt.
lastUserActivityAt is an ISO 8601 time, in UTC or with an offset: the agent's last real user or channel message, omitted while it has none. Any other value is ignored and logged, so the heartbeat still gets its commands. For a managed agent the time counts as user activity. It is stored when it is newer than the stored activity (or, with none stored, the agent's creation time), and a time up to 5 minutes ahead of Vouched KYA's clock is read as now; one further ahead is ignored and logged. When the time earns a better activity tier than the agent's current one, the agent is promoted: active within 7 days, idle within 30. A heartbeat returns update_config for the new tier only once the agent has had no user activity for 5 minutes, since applying it restarts the gateway. User activity is a dashboard chat opened or restarted, a thread note, the start or end of a thread turn, and a lastUserActivityAt reported here, so a channel-only agent keeps the update waiting only while its heartbeats carry that field. Until the update is sent the gateway keeps the previous tier's heartbeat interval and model, though the dashboard already shows the new tier, and a turn still running more than 5 minutes after the last user activity can be interrupted when it is applied. A report never demotes an agent. BYOK agents' reports are ignored.
Response:
200 with the raw heartbeat object (this endpoint does not use the { success, data } envelope):
{
"ack": true,
"commands": [{ "type": "update_config" }],
"configUpdatedAt": "2026-08-19T12:00:00.000Z"
}commands this handler actually emits: { "type": "stop" } when the deployment has been killed, and { "type": "update_config" } when the deployment's config changed since the container last fetched its bundle, except that a tier change made while the agent has had user activity in the last 5 minutes is held until it has been quiet that long. The shared ComputeCommandSchema also declares restart and update_version command types, but this handler never emits either: treat them as reserved.
Errors: 401 AUTH_UNAUTHORIZED for a missing/invalid heartbeat token or unrecognized agentDid, 429 RATE_LIMIT_EXCEEDED, 400 VALIDATION_BAD_REQUEST for invalid JSON, a body that fails schema validation, or a body agentDid that does not match the URL parameter, 503 SERVICE_UNAVAILABLE_TRANSIENT (with Retry-After: 2) when the database is cold-starting: back off and retry.
Get Config Bundle
Returns the agent's full runtime configuration. Fetched by the compute process on boot and again whenever a heartbeat returns an update_config command. The response contains live secrets (channel tokens, gateway token, AI provider key) and is served with Cache-Control: no-store.
Endpoint: GET /api/v1/molti/deployments/{agentDid}/config-bundle
Auth: Dual, by hosting mode. Managed deployments: X-Heartbeat-Token header (per-deployment token, timing-safe compare). BYOK deployments: API key (X-API-Key or Authorization: Bearer) whose project matches the deployment's project. An unrecognized agentDid returns 401, not 404, to prevent DID enumeration.
Request: no body. The agentDid path segment is the URL-encoded agent DID.
Response:
200 with { success: true, data: bundle }. Managed deployments get a version 2 bundle:
{
"success": true,
"data": {
"version": 2,
"killed": false,
"openclawVersion": "2026.8.1",
"soulFile": "...",
"gatewayToken": "...",
"channels": {
"telegram": { "enabled": true, "token": "..." },
"discord": { "enabled": false },
"slack": { "enabled": true, "token": "...", "appToken": "..." },
"whatsapp": { "enabled": true }
},
"aiProvider": { "type": "anthropic", "apiKey": "..." },
"updatedAt": "2026-08-19T12:00:00.000Z",
"meta": {
"lastTouchedVersion": "2026.8.1",
"lastTouchedAt": "2026-08-19T12:00:00.000Z"
},
"configHash": "sha256-hex..."
}
}Notes on the managed bundle:
aiProvider.typeisanthropicoropenai. For managed-LLM deployments,aiProvideralso carriesbaseUrl(the Vouched KYA LLM proxy) and itsapiKeyis the gateway token.heartbeatEveryandmodelOverride(tier-driven overrides) are included only when the deployment's OpenClaw version supports them; older runtimes get the bundle without those fields.channelsentries are omitted (undefined) for channels that were never configured;whatsappcarries onlyenabled.- Fetching the bundle records config acknowledgment (
lastConfigAckAt), which is what stops the heartbeat from re-sendingupdate_config.
BYOK deployments get a version 1 bundle: { version: 1, killed, soulFile, channels, updatedAt } only.
The agent's private key is never included in either bundle; it is delivered as an environment variable at machine creation.
Errors: 401 AUTH_MISSING_CREDENTIALS when no credential is presented at all (or a BYOK deployment presents no API key), 401 AUTH_UNAUTHORIZED for an unrecognized agentDid, an invalid heartbeat token, or an API key that does not belong to the deployment's project, 500 INTERNAL_SERVER_ERROR when no OpenClaw version is configured for a managed deployment, 500 DECRYPTION_FAILED when the stored gateway token cannot be decrypted.
OpenClaw Integration APIs
Endpoints that let an OpenClaw runtime use Vouched KYA as its tool-policy provider and approval backend. config and approve are API-key endpoints; the consent endpoint is part of the browser-based consent flow and authenticates by consent token instead, by design.
The config and approve endpoints use the shared v1 error envelope ({ success: false, error: { code, message, details? }, metadata: { requestId, timestamp, version: "v1" } }, plus X-Request-ID and X-API-Version: v1 headers); the consent endpoint uses the base envelope without the version field.
Get OpenClaw Tool Policies
Returns the project's tool protections translated into OpenClaw's native tools.policyProvider format.
Endpoint: GET /api/v1/openclaw/config
Auth: API key (X-API-Key, or Authorization: Bearer) with access to the requested project.
Request:
Response:
200 with { success: true, data } (no top-level metadata on this endpoint; the metadata block lives inside data). Served with Cache-Control: public, max-age=60.
{
"success": true,
"data": {
"tools": {
"policies": {
"gmail_send_email": {
"approval": "always",
"riskLevel": "high",
"authorization": {
"type": "oauth2",
"provider": "google",
"requiredScopes": ["email:send"]
}
},
"read_file": {
"approval": "off",
"riskLevel": "low"
}
}
},
"metadata": {
"refreshInterval": 60,
"source": "agentshield",
"projectId": "acme-corp",
"timestamp": "2026-08-19T12:00:00.000Z",
"requestId": "req_abc123"
}
}
}Per-tool policy fields: approval is always when the tool requires delegation, otherwise off (the type also declares auto, but this handler never emits it). riskLevel (low | medium | high | critical), authorization (type, plus provider and requiredScopes for OAuth types, provider for password type), and requiredScopes appear when configured. A project with no configured tools returns an empty policies object; a failed tool-protection lookup also degrades to empty policies rather than erroring, so OpenClaw keeps functioning.
Errors: 400 MISSING_PROJECT_ID when the query parameter is absent, 404 PROJECT_NOT_FOUND, 500 PROJECT_LOOKUP_FAILED on a failed project lookup, 403 PERMISSION_FORBIDDEN when your API key is not scoped to this project, 401 AUTH_MISSING_CREDENTIALS / AUTH_INVALID_API_KEY for missing or invalid keys, 429 RATE_LIMIT_EXCEEDED.
Approval Webhook
Called by OpenClaw's approval workflow when a protected tool is invoked. Low-risk tools are approved immediately with a signed delegation token (a W3C VC-JWT, also persisted as an active delegation). Tools that need a human are parked as a pending approval, and the response carries a consent URL to put in front of the user.
Endpoint: POST /api/v1/openclaw/approve
Auth: API key (X-API-Key, or Authorization: Bearer). The key must be project-scoped: the project is resolved from the key, not the body.
Request:
{
"tool": "gmail_send_email",
"args": { "to": "user@example.com", "subject": "Hello" },
"agentDid": "did:key:z6Mk...",
"sessionId": "session-123",
"userDid": "did:web:kya.vouched.id:orgs:acme:users:user_123",
"requireHumanApproval": false,
"callbackUrl": "https://agent.example.com/callback",
"metadata": {}
}Required fields: tool (1-255 chars), agentDid (1-500 chars). Optional: args (object), sessionId, userDid, requireHumanApproval (boolean), callbackUrl (URL, SSRF-validated), metadata (object).
On an approval that needs a human, userDid names who may decide it, so it must be the Vouched KYA user DID of a member of the project's org (did:web:kya.vouched.id:orgs:<org>:users:<id>, with the account id in lowercase, as Vouched KYA writes it). Any other DID, such as a did:key, a non-member's, or a member's id in uppercase hex, is refused with 400 INVALID_USER_DID, since nobody could decide that approval. To name the approver by email instead, set metadata.user_email (or metadata.email). It must be the account email of a member of the project's org, compared case-insensitively, or the request is refused with 400 INVALID_USER_EMAIL. When both are given, they must name the same member. An approval that's approved immediately takes any userDid and any metadata.
Human approval is required when any of these holds: the request sets requireHumanApproval, the tool's protection has riskLevel high or critical, or the tool has requiresDelegation: true. Scopes come from the tool protection's requiredScopes, defaulting to ["{tool}:execute"].
Response:
200 with { success: true, data, metadata: { requestId, timestamp } }. data is one of two shapes:
Immediate approval (token valid 1 hour):
{
"approved": true,
"delegationToken": "eyJ...",
"expiresAt": "2026-08-19T13:00:00.000Z",
"scopes": ["email:send"],
"requestId": "..."
}Pending human approval (request valid 15 minutes):
{
"approved": false,
"pending": true,
"consentUrl": "https://kya.vouched.id/consent/{requestId}?token=...",
"requestId": "...",
"expiresAt": "2026-08-19T12:15:00.000Z"
}The route's own doc comment also describes a denied shape (approved: false, denied: true), but this handler has no code path that emits it: every valid request is either approved immediately or routed to human consent. Denials happen on the consent endpoint below.
If callbackUrl was provided, the consent endpoint will POST the final result to it when the human completes the flow.
Errors: 400 INVALID_REQUEST_BODY for unparsable JSON, 400 VALIDATION_ERROR for a body that fails the schema, 400 NO_PROJECT when the API key is not associated with a project, 404 PROJECT_NOT_FOUND, 500 PROJECT_LOOKUP_FAILED, 503 TOOL_PROTECTION_LOOKUP_FAILED on a failed tool-protection read (deliberately an error, never a silent auto-approve: retry), 400 INVALID_CALLBACK_URL for a callback URL that fails SSRF validation, 400 INVALID_USER_DID for a userDid that isn't the user DID of a member of the project's org on an approval that needs a human, 400 INVALID_USER_EMAIL for a named email that isn't a member's account email (or isn't the email of the member userDid names), 500 PENDING_APPROVAL_FAILED / TOKEN_GENERATION_FAILED on a failed persist or signing step, plus 401 AUTH_* and 429 RATE_LIMIT_EXCEEDED from the shared v1 middleware.
Consent Completion
The consent flow endpoint behind the consentUrl returned by the approval webhook. GET feeds the consent UI; POST completes the approval.
Endpoint: GET or POST /api/v1/openclaw/consent/{requestId}
Auth: GET: none. POST needs two things:
- the consent token minted by the approval webhook, passed in the body (
token) or as a?token=query parameter; - a signed-in Vouched KYA account that belongs to the project's organization, sent from a page on this host.
The token binds the request to the link; it never decides alone. When the approval names a user (a userDid, which must be the member's Vouched KYA user DID, or an email in its metadata), only that user can decide it. Neither method takes an API key, by design.
There is no Vouched KYA page for deciding an OpenClaw approval yet, so a consentUrl can't be completed in a browser today.
Request:
GET takes no body. POST body:
{
"action": "approve",
"reason": "optional, max 500 chars",
"token": "consent token, if not in the query string"
}action is required: approve or deny. reason is stored as the denial reason on deny (defaults to "User declined").
Response:
GET returns 200 with { success: true, data }:
{
"success": true,
"data": {
"requestId": "...",
"tool": "gmail_send_email",
"agentDid": "did:key:z6Mk...",
"scopes": ["email:send"],
"args": { "to": "user@example.com" },
"expiresAt": "2026-08-19T12:15:00.000Z",
"status": "pending",
"projectId": "...",
"projectName": "My Project"
}
}status reads expired when the request is past its expiry but was still pending; otherwise it is the stored status.
POST returns 200 with { success: true, data }, where data is the approved shape (approved: true, delegationToken valid 1 hour, expiresAt, scopes, requestId) or the denied shape (approved: false, denied: true, reason, requestId). The delegation token acts as the signed-in approver: their user DID and email, in a session of its own for this approval. It never carries a user or session the approval request named. Each approval gets a delegation of its own, even when the same approver approves the same agent and tool again. Completion is guarded by optimistic locking, so two racing completions cannot both win. If the original approval request carried a callbackUrl, the result is also POSTed there fire-and-forget as { event: "approval_completed", requestId, approved, ... }; callback failures never affect the approval itself.
Errors: 404 REQUEST_NOT_FOUND for an unrecognized requestId (both methods). POST only: 400 INVALID_REQUEST_BODY for unparsable JSON, 400 VALIDATION_ERROR when action is missing or invalid, 401 MISSING_CONSENT_TOKEN / INVALID_CONSENT_TOKEN for an absent or failed token check, 400 REQUEST_ALREADY_COMPLETED when the request was already completed, 400 REQUEST_EXPIRED when it expired before completion, 403 CROSS_ORIGIN_DECISION when the decision did not come from a page on this host, 401 SIGN_IN_REQUIRED with no signed-in Vouched KYA account, 403 APPROVER_NOT_ORG_MEMBER when the account is outside the project's organization, 403 APPROVER_NOT_NAMED_USER when the approval names a different user, 409 REQUEST_ALREADY_COMPLETED when a concurrent completion won the race.
Fingerprint
Testing and profiling endpoints for the fingerprinting system. These do not use the standard v1 envelope consistently, most take no authentication, and several exist to feed the internal comparison and profiling tools.
POST /fingerprint/collect, GET /fingerprint/comparison/{testId}, POST /fingerprint/comparison/log, POST /fingerprint/detect and POST /fingerprint/test set no CORS headers of their own and have no OPTIONS handler, so a preflight is answered by the framework with a 204 and an Allow header. The API-wide CORS policy applies to every response of theirs, the preflight included: Access-Control-Allow-Origin: *, Access-Control-Allow-Methods: GET,OPTIONS,PATCH,DELETE,POST,PUT and Access-Control-Allow-Headers: X-CSRF-Token, X-Requested-With, Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Api-Version, X-API-Key, and never Access-Control-Allow-Credentials. Authorization and X-Gateway-Key are not in that list, so a browser cannot send either on a cross-origin request. /fingerprint/enhanced sets CORS headers itself on its POST response only. GET/POST /fingerprint echo an allow-listed Origin rather than *.
The fingerprint endpoints are testing and profiling tools, not part of the supported public
contract: most take no authentication, return _debug payloads, and do not use the standard v1
response envelope. Treat them as internal tooling until the contract says otherwise.
Capture Request Fingerprint
Endpoint: GET /api/v1/fingerprint or POST /api/v1/fingerprint
Auth: none. The route runs through the core API middleware with requireAuth: false.
Request: no body required. Optional query parameters test or id tag the capture with a test identifier for the fingerprint log. A POST body of any content type is echoed back in the response (body, bodyType, contentType); JSON is parsed, anything else is read as text.
Response: 200 with { success: true, data, metadata: { requestId, timestamp } }. data is the captured fingerprint (shape derived from the FingerprintResponse type plus route-added debug fields):
- Echo of the request:
timestamp,method,url,path,queryParams,headers(every request header, lowercased, with credentials redacted as below),headerCount,ip(fromx-vercel-forwarded-for, thenx-forwarded-for, thenx-real-ip; literal"unknown"when none resolves),httpVersion fingerprint: rule-engine analysis (hasChromiumHeaders,hasBrowserHeaders,hasSecFetchHeaders,isAutomated,suspiciousPatterns,confidence,detectedAgent,isLikelyBot,isLikelyAI, plusrulesAppliedandbreakdowndebug detail)analysis: named header extracts (userAgent,acceptHeader,acceptLanguage,acceptEncoding,hasReferer,hasCookies,hasAuthorization, and thesec-ch-ua*/sec-fetch-*values), each"Not provided"when absentdetection:{ isLikelyBot, isLikelyAI, agentType, confidence }whereconfidenceis a percent string such as"92%"_debug:rulesApplied,breakdown,processingTime
Two more things worth knowing before you read the numbers. fingerprint.confidence is clamped to the 0 to 1 range (both by the shared schema and by the rule engine), and detection.isLikelyBot tests fingerprint.confidence > 0.7. It is a different verdict from fingerprint.isLikelyBot (the rule engine's own isBot), and the two can disagree. And httpVersion is derived from an http2 request header that does not exist, so it is always the literal HTTP/1.1.
data.headers echoes every inbound header back, except that credential values are replaced with [redacted]: any header whose name contains auth, cookie, credential, delegation, jwt, key, password, secret, session, signature or token, and every x-vercel-* header other than x-vercel-id, x-vercel-forwarded-for, x-vercel-deployment-url, x-vercel-ja4-digest and the x-vercel-ip-* geo headers. The RFC 9421 headers signature, signature-input and signature-agent keep their values. The names stay, so headerCount, analysis.hasCookies and analysis.hasAuthorization still count them. The fingerprint log stores the same redacted copy. /fingerprint/enhanced does the same.
Errors: the standard error envelope via the shared error handler: 500 INTERNAL_SERVER_ERROR / INTERNAL_UNKNOWN_ERROR on an unexpected failure. A 400 is unreachable here, since neither handler parses a request schema and a POST body that cannot be read becomes a 200 with body: "Unable to parse body". Error responses carry only the API-wide Access-Control-Allow-Origin: * (no credentials) and no Cache-Control.
Enhanced Fingerprint Capture
Endpoint: GET /api/v1/fingerprint/enhanced or POST /api/v1/fingerprint/enhanced
Auth: none.
Request: no body required. Optional test / id query parameters as above. A JSON POST body is treated as client-side detection data (the route uses body.clientDetection when present, otherwise the whole body) and is folded into the analysis, including a Perplexity-specific detector; body.metadata.testIdentifier overrides the query parameter. Request shape is derived from property reads, not a Zod schema: there is no validation, and any body is accepted.
Response: 200, not enveloped: the fingerprint object is the response body. Everything from the base capture endpoint plus:
enhanced:tls(version,cipherSuites,ja3,ja3s, read fromx-tls-*/x-ja3*proxy headers when present),network(ttfb,tcp),processingTime,ipInfo(primary,allForwarded),suspiciousHeaders(nonstandardx-*headers),missingHeaders(browser headers absent from the request)metadata: flattened detection summary for storage (isAgent,isAI,confidenceas a number,agentType,ipAddress,userAgent,url,method,detectionMethod,factors,testIdentifier)_debug: addsadditionalMetadata(informational observations) andperplexityDetection(isPerplexity,confidence,signals,matchedPatterns)- POST also echoes
body,bodyAnalysis(hasBody,bodyType,bodySize,isJson,jsonKeys),contentType
Responses carry X-Fingerprint-Version: enhanced-v1. The POST response also carries Access-Control-Allow-Origin: * with an allow-headers of *; the GET response sets none of its own and carries only the API-wide Access-Control-Allow-Origin: *.
Only four enhanced.tls members (version, cipherSuites, ja3, ja3s) and two enhanced.network members (ttfb, tcp) are ever populated, and on Vercel all six are absent: the proxy headers they are read from are never set.
One number can leave its documented range here. When the Perplexity override fires it forces fingerprint.detectedAgent to the literal Perplexity AI and sets the confidence to max(engineConfidence, perplexityConfidence + signalCount * 0.1) without clamping, so fingerprint.confidence can exceed 1 and the derived metadata.confidence can exceed 100. The same override pushes its signals into fingerprint.suspiciousPatterns, which is the same array object as _debug.breakdown.factors, so they appear in both.
Errors: GET answers an unexpected failure with 500 { success: false, error: "Failed to capture enhanced fingerprint" }; the underlying error is logged server-side and never returned. POST has no error response: its single try turns a body-read failure into a 200 with bodyAnalysis.bodyType: "error", and any other failure surfaces as a framework 500 with no body of ours, not the standard error envelope. Neither operation has a 4xx, because neither validates any input.
Collect Fingerprint Data
Endpoint: POST /api/v1/fingerprint/collect
Auth: none. Rate limited per client IP: a burst of 5 per 10 seconds, 1 request/second and 10/minute. There is no hourly window. Successful responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset.
Request: validated by CollectFingerprintRequestSchema (@kya-os/checkpoint-shared):
{
"testId": "test-abc123",
"integrationType": "beacon",
"data": {
"clientSide": { "canvas": { "hash": "..." }, "webgl": {}, "audio": {} },
"behavioral": {},
"metadata": { "collectionDuration": 120, "errors": [], "warnings": [] }
}
}integrationType (required): one of pixel, beacon, noscript, middleware, express, edge, wasm. testId optional. data is z.any() in the schema, so its interior is not validated; the keys shown are the ones the handler reads (clientSide is stored only for pixel/beacon, request headers are stored for the server-side types, geo-enhanced server data for middleware/express). The geo data attached for middleware/express is read from the edge headers Vercel and Cloudflare populate (country, and region/city when present) and is omitted entirely when the edge reported no country; latitude, longitude and timezone are never available from those headers and are never populated.
The stored record is raw collection data with a preliminary, low-confidence classification; real detection runs later via the detect endpoint. The stored request headers have credential values replaced with [redacted] by the same rule as the GET /fingerprint echo (see Capture Request Fingerprint); the names stay, and the preliminary classification reads the values as received. When testId starts with test-, the result is also forwarded to the comparison log (fire-and-forget) as the pixel source.
Response: 200 validated by CollectFingerprintResponseSchema:
{
"success": true,
"sessionId": "V1StGXR8_Z5jdHi6B-myT",
"fingerprintId": "0b7f6c9e-...",
"message": "Fingerprint collected successfully via beacon"
}fingerprintId is the stored row id (use it with the detect and test endpoints); sessionId is a per-collection identifier generated by this request.
Errors: 400 VALIDATION_BAD_REQUEST for unparsable JSON, 400 VALIDATION_INVALID_REQUEST with field details for a schema failure, 429 RATE_LIMIT_EXCEEDED, 500 INTERNAL_SERVER_ERROR otherwise (all in the standard error envelope). Two caveats: the 429 carries no X-RateLimit-* headers and no Retry-After, because those headers are built only on the success path (the body's error.details carries limit and retryAfter, which is null on a per-second or per-minute refusal and 10 seconds only on a burst refusal); and the route validates its own 200 body before sending it, so a server-side contract violation surfaces as a 500 INTERNAL_SERVER_ERROR (Response failed schema validation), never as a 400.
Run Detection on a Fingerprint
Endpoint: POST /api/v1/fingerprint/detect
Auth: none.
Request: { "fingerprintId": "<uuid>" }, parsed against a Zod schema. fingerprintId must be a UUID, because fingerprints.id is a uuid column and a value that is not one cannot address a row: it comes back as a 400 before any query runs. A missing, empty or non-string fingerprintId is the same 400. The body carries exactly one member; any other member you send is ignored rather than rejected.
Runs the kya-os detection engine over the stored fingerprint and writes the results back to the row (this endpoint mutates the record). The route was migrated off the retired agentshield_wasm engine; the persisted detection_results.wasm_detection_complete key keeps its old name for backward compatibility with the admin UI.
Response: 200, not enveloped:
{
"success": true,
"fingerprintId": "0b7f6c9e-...",
"detection": {
"is_agent": true,
"confidence": 0.92,
"agent_type": "chatgpt",
"verification_method": "pattern",
"risk_level": "high",
"detection_class": "ai_agent",
"signature_verified": false,
"detection_time_ms": 12
},
"message": "Detected as chatgpt with 92% confidence"
}confidence here is on the engine's 0 to 1 scale; the persisted fingerprints.confidence column stores the same number multiplied by 100 and rounded. (POST /api/v1/pixel-wasm reports the opposite scale, 0 to 100, for the same kind of value.) signature_verified is true when the engine's verification_method indicates cryptographic verification. is_agent is deliberately not the engine's bare isAgent flag: a crawler or bot verdict the engine expresses only through detection_class still counts as non-human here.
Errors: non-standard shapes ({ success: false, error: "<string>" }), each error a fixed string: 400 "Invalid JSON body" when the body is not valid JSON, 400 "fingerprintId is required and must be a UUID" (the body is parsed, so a non-UUID is refused before the query rather than reaching Postgres), 404 "Fingerprint not found", 500 "Detection engine error" when the engine call throws, 500 "Failed to run detection" otherwise. The underlying error is logged server-side and never returned. Error error is a plain string, not the { code, message } object used elsewhere.
Simulate Detection Across Integration Types
Endpoint: POST /api/v1/fingerprint/test
Auth: none.
Request: validated by TestDetectionRequestSchema: { "fingerprintId": "<uuid>", "integrationTypes": ["pixel", "beacon"] }. integrationTypes optional; defaults to all seven. This endpoint runs a simplified simulation per integration type, not Vouched KYA's detection engine, and stores a test-run record. It also overwrites the fingerprint row's behavioral_data with the test result and can update its ai_type/confidence, so it mutates state.
Response: 200, not enveloped:
{
"fingerprintId": "0b7f6c9e-...",
"timestamp": "2026-08-19T12:00:00.000Z",
"results": {
"pixel": {
"isAgent": true,
"confidence": 0.85,
"agentType": "chatgpt",
"vendor": "openai",
"reasons": ["GPT user agent pattern"],
"processingTime": 3
}
},
"summary": {
"consensusIsAgent": true,
"averageConfidence": 0.72,
"mostLikelyAgent": "chatgpt",
"integrationAgreement": 71.4
},
"recommendations": ["Strong consensus: 5/7 integrations detected an agent"]
}results has one entry per tested integration type. averageConfidence is a mean on the 0 to 1 scale, while integrationAgreement is a percentage 0 to 100: the two scales differ inside the same object. Per-integration confidence is also 0 to 1 and is clamped, including the wasm entry's 1.1x boost.
Passing integrationTypes: [] is not the same as omitting it, and it is not a "test nothing" call: no integration would run and both summary means would be divisions by zero. The request schema requires at least one entry, so an empty array is a 400, and neither summary member is nullable.
A detection failure inside one integration is not an error response: that integration's reasons carries the fixed entry "Error: detection failed" on the 200, and the underlying error is logged server-side, never returned or stored.
Errors: 400 { success: false, error: "Invalid JSON body" } when the body is not valid JSON. 400 { success: false, error: "Validation error", details: [...] } when the body fails the request schema (including a fingerprintId that is not a UUID), where details is the raw Zod issue array. 404 { success: false, error: "Fingerprint not found" }. Every other failure returns 500 { success: false, error: "Detection test failed" }. The underlying error is logged server-side and never returned. Error error is a plain string.
Log a Comparison Result
Endpoint: POST /api/v1/fingerprint/comparison/log
Auth: split by source. middleware and pixel submissions are unauthenticated. gateway submissions must present the internal gateway key (X-Gateway-Key: <key> or Authorization: Bearer <key>, checked against the GATEWAY_INTERNAL_KEY environment secret); a missing or wrong key returns 401 { success: false, error: "Unauthorized - invalid gateway key" }. When the secret is unconfigured on the server, every gateway submission is rejected. The gateway leg is for the Gateway Worker, not customers.
Aggregates detection results from the three methods under one testId for side-by-side comparison. Each source upserts its own column set, so the three can arrive in any order; methodsAgree is recomputed once at least two are present.
Request: validated by an inline Zod schema:
{
"testId": "test-abc123",
"source": "middleware",
"detection": {
"isAgent": true,
"confidence": 92,
"agentName": "ChatGPT-User",
"agentType": "chatgpt",
"detectionClass": "ai_agent",
"verificationMethod": "pattern",
"reasons": ["..."],
"signatureVerified": false,
"metadata": {}
},
"metadata": {
"tlsFingerprint": { "ja3Fingerprint": "..." },
"processingTimeMs": 42,
"fingerprintId": "0b7f6c9e-...",
"userAgent": "Mozilla/5.0...",
"ipAddress": "203.0.113.7"
}
}testId must start with test-. source is gateway | middleware | pixel. detection.confidence is 0 to 100 here (unlike the detect endpoint's 0 to 1). All metadata fields are optional; tlsFingerprint (ciphersSha1, extensionsSha1, httpProtocol, tlsVersion, clientHelloLength, ja3Fingerprint) is meaningful for the gateway source, and the read endpoint reports only its presence; fingerprintId is meaningful for pixel.
Response: 200, not enveloped:
{
"success": true,
"testId": "test-abc123",
"source": "middleware",
"comparisonId": "7c1d...",
"message": "Detection logged from middleware",
"methodsLogged": { "gateway": false, "middleware": true, "pixel": true },
"methodsAgree": true
}methodsAgree is null until at least two sources have logged.
Only the gateway source is authenticated. A middleware or pixel submission is accepted from anyone, and the body metadata.ipAddress is honoured only for gateway; for the other two the address is resolved from the request boundary and the submitted value is ignored. The schema parse also runs before the gateway key is checked, so an unauthenticated caller can provoke the validation 400.
Errors: 401 invalid gateway key (gateway source only, and returned identically when the server has no gateway key configured at all, so the two are indistinguishable), 400 { success: false, error: "Invalid JSON body" } when the body is not valid JSON, 400 { success: false, error: "Invalid testId format - must start with \"test-\"" }, 400 { success: false, error: "Validation error", details: [...] } for a schema failure (details is the raw Zod issue array, not the flattened form other routes use), 500 { success: false, error: "Failed to log comparison" } otherwise. The underlying error is logged server-side and never returned. Error error is a plain string.
Get Comparison Results
Endpoint: GET /api/v1/fingerprint/comparison/{testId}
Auth: none. Anyone holding a testId can read its comparison record, so the response carries detection verdicts only: no visitor user agent, IP address, collected fingerprint data or TLS fingerprint values.
Response: 200, not enveloped; a fixed shape assembled from the stored row:
{
"success": true,
"testId": "test-abc123",
"comparisonId": "7c1d...",
"gateway": {
"detected": true,
"detectedAt": "2026-08-19T12:00:00.000Z",
"detection": { "isAgent": true, "confidence": 92 },
"hasTlsFingerprint": true,
"processingTimeMs": 8
},
"middleware": {
"detected": true,
"detectedAt": "2026-08-19T12:00:01.000Z",
"detection": { "isAgent": true, "confidence": 88 },
"processingTimeMs": 42
},
"pixel": {
"detected": false,
"detectedAt": null,
"detection": null,
"fingerprintId": null,
"hasClientFingerprints": false
},
"summary": {
"methodsLogged": 2,
"methodsAgree": true,
"consensusResult": "AI Agent (ChatGPT-User)",
"discrepancies": []
},
"createdAt": "2026-08-19T12:00:00.000Z",
"updatedAt": "2026-08-19T12:00:01.000Z"
}Each source block's detection is what that source logged, projected to a fixed field list: isAgent and confidence, plus agentName, agentType, detectionClass, verificationMethod, reasons and signatureVerified when the stored value holds them with the declared type. reasons keeps only its string entries, and the metadata bag the log endpoint accepts is never returned. A stored detection without a boolean isAgent and a numeric confidence comes back as null. gateway.hasTlsFingerprint is true when the gateway source stored a TLS fingerprint; the TLS values themselves are never returned. The {testId} path segment is matched against a varchar(255) column with no format check on this read path: the test- prefix the write endpoint enforces is not required here. pixel.hasClientFingerprints is true when the linked fingerprint row exists and carries client-side fingerprints, and false otherwise; the fingerprint data itself is never returned. summary.consensusResult is "AI Agent (<name>)", "Human", or "Inconclusive" by majority vote; when the majority says agent but no source named one, the literal string is "AI Agent (Unknown)" (a code literal, quoted as emitted). discrepancies lists human-readable disagreement notes (isAgent splits, confidence spread over 30 points, agent-name mismatches).
Errors: 404 { success: false, error: "Comparison not found", testId }, 400 "testId is required" (unreachable through normal routing since the path segment is always present), 500 { success: false, error: "Failed to get comparison" } otherwise (the underlying error is logged server-side and never returned). Error error is a plain string.
Platform Status
Get Platform Status
Public platform health report. Backs the /status page and any external monitor a customer points at Vouched KYA.
Endpoint: GET /api/v1/status
Auth: None, public and unauthenticated by design.
Request: No parameters.
Response:
{
"overall": "operational",
"checks": [
{
"id": "db",
"label": "Database",
"description": "One-line description of what the check proves",
"group": "platform",
"status": "operational",
"latencyMs": 12,
"detail": null
}
],
"generatedAt": "2026-07-27T12:00:00.000Z",
"version": "1.2.3"
}overall is operational, degraded, or major_outage. Each check's status is operational, degraded, down, or not_configured (not_configured checks are excluded from the overall rollup). group is platform, engines, or edge. latencyMs is null for checks that never ran; version is null when the runtime does not expose the web app version. detail carries only a fixed public vocabulary (versions, mapped failure codes), never raw error messages.
Results are memoized server-side and returned with Cache-Control: public, s-maxage=<ttl>, stale-while-revalidate=<4x ttl> (the route comments state a 30 second window), so polling cannot stampede the underlying probes.
Errors: None structured. Failures inside individual probes are folded into per-check status values rather than error responses; an unexpected handler failure would surface as a framework 500.
Documentation Search
Search Documentation
Full-text search over the documentation pages. This backs the docs site's search box; it searches documentation content only, not customer data.
Endpoint: GET /api/v1/search
Auth: None, public.
Request:
An empty or missing query returns an empty result list.
Response:
{
"results": [
{
"title": "Public API Reference",
"url": "/docs/api-reference",
"description": "Complete reference for the Checkpoint REST API"
}
]
}Results are sorted by relevance (title matches rank above description matches, which rank above body matches). description may be absent.
Errors: 500 with { "results": [], "error": "Search failed" } on an unexpected failure. Note this is not the standard error envelope used by the authenticated endpoints.
Infrastructure and Demo Endpoints
The endpoints below exist under /api/v1 but are not part of the supported customer integration contract. They are documented here for completeness and honesty about the surface.
Managed LLM Proxy (Anthropic Messages)
Platform infrastructure for managed-mode deployments, not a customer-callable API. Forwards Anthropic /v1/messages requests on behalf of managed deployments: the deployment's OpenClaw runtime presents its per-deployment gateway token, and Vouched KYA forwards to api.anthropic.com using a platform-owned shared key while metering a per-deployment token budget. BYOK deployments do not use this route; they call Anthropic directly with their own key.
Endpoint: POST /api/v1/llm/anthropic/v1/messages
Auth: Per-deployment gateway token in the x-api-key header (the same header slot Anthropic's own API uses, so the SDK needs no changes). Not a Vouched KYA API key. The whole route is behind a kill switch: unless the MANAGED_LLM_ENABLED environment variable is true, it returns a plain 404 Not Found.
Request: the Anthropic Messages request body, forwarded byte-for-byte to the upstream (default https://api.anthropic.com/v1/messages, overridable by environment). The anthropic-version header is forwarded (defaulting to 2023-06-01) and anthropic-beta is forwarded when present. The top-level stream flag in the body selects streaming.
Response: the upstream Anthropic response, status and body forwarded. Streaming responses (text/event-stream) are piped through with usage frames (message_start, message_delta) tapped for budget accounting without buffering; non-streaming and all non-2xx upstream responses are returned as JSON. A non-2xx upstream is always returned as JSON even for a streaming request, matching Anthropic's own behavior for pre-flight errors.
Errors: Anthropic-style bodies, { "type": "error", "error": { "type": "...", "message": "..." } }:
401 authentication_error: missing or invalidx-api-key(no matching live managed deployment)429 rate_limit_error: the deployment's token budget is exhausted (a missing or zero budget counts as exhausted, fail-closed; carriesretry-after: 86400)502 server_error: upstream unreachable, or an empty upstream stream503 server_error: platform upstream key not configured- Upstream Anthropic errors pass through with their original status and body
Generate Demo Data
Demo-only endpoint that generates synthetic session and detection data for product demos. Unauthenticated, reads and writes no customer data, and every response is stamped demo: true. Do not build integrations against it.
Endpoint: POST /api/v1/demo/generate (a GET variant exists for simple testing)
Auth: None.
Request: POST body: { url?: string (must be a valid URL), count?: number (1 to 20, default 5) }. GET accepts the same as url and count query parameters, with count capped at 10.
Response:
{
"success": true,
"sessions": [{ "sessionId": "demo_...", "isAgent": true, "...": "..." }],
"metadata": {
"totalSessions": 5,
"totalDetections": 23,
"agentSessions": 4,
"humanSessions": 1,
"demo": true,
"generatedAt": "2026-07-27T12:00:00.000Z",
"requestId": "req_abc123"
}
}Each generated session mirrors the shape of real session data (sessionId, agentType, isAgent, confidence, ipAddress, userAgent, paths, detectionReasons, detectionSources, per-event events[], and more), with weighted random agent types (ChatGPT, Claude, Perplexity, Grok, Human). Note one wrinkle: for human sessions agentType carries the literal string Unknown, which is not a real detection class (demo filler only); do not branch on it.
Errors: 400 VALIDATION_BAD_REQUEST for a non-JSON POST body, 400 VALIDATION_INVALID_REQUEST when the body fails schema validation (e.g. count out of range).
WASM Detection (Pixel Support)
A dedicated WASM detection endpoint designed to be called by the main pixel endpoint for separation of concerns. It is unauthenticated and CORS-open, but it is a service-support endpoint, not a supported public contract; integrations should use /api/v1/detect instead.
Endpoint: POST /api/v1/pixel-wasm (plus OPTIONS for CORS preflight)
Auth: None.
Request: JSON body with userAgent, ipAddress, headers, url, method (property reads, no schema validation; all effectively optional with fallbacks).
Response: 200 with { success: true, detection: { isAgent, confidence, detectionClass, signals, agent, agentType, detectedAgent, verificationMethod, riskLevel, timestamp } }. confidence is on the 0 to 100 scale. On an internal detection failure the endpoint still returns 200 with a zeroed stub result (isAgent: false, confidence: 0) rather than an error.
Errors: None specific; an unexpected handler failure goes through the shared error handler.
Rate Limits
Default API rate limits by plan:
These endpoints count against your plan's rate limits:
/detectcounts per API key and enforces a burst limit (5 requests per 10 seconds on Free, 200 on Enterprise), the per-second limit, and the per-minute limit./projectsand every/projects/{projectId}endpoint,/detections/{id}and its sub-routes such as/detections/{id}/labels,/shopify/projects/*,/deploy/managed, the/webhooksendpoints,/openclaw/config,/openclaw/approve, the API-key/bouncer/projects/{projectId}/*endpoints, the CLI endpoints (/cli/*), and/agents/lifecyclecount per account and enforce the per-minute limit only. They all draw on one per-minute budget, and so does any other API-key endpoint under these paths.
* The per-day figure is your plan's quota, not a runtime-enforced limit.
Detection responses (/detect) include rate limit headers:
X-RateLimit-Limit: Maximum requests allowed in the per-minute window (this header always reports the minute limit, not the per-second or per-day figures above)X-RateLimit-Remaining: Requests remainingX-RateLimit-Reset: Time when limit resets (Unix timestamp)
Enforcement responses (/enforce) carry KYA-* headers instead: see Evaluate Request.
The public ingestion endpoints are keyed differently: /pixel counts per client IP and pixel
against the project owner's per-minute limit, and /pixel/track per client IP and project
against the Free per-minute limit. The OAuth endpoints are rate-limited per client IP. Their per-endpoint notes call out
any deviations (for example /pixel/track's RATE_LIMITED code, or the gateway OAuth surface's
RFC 6749-shaped rate_limit_exceeded).
Error Handling
Vouched KYA uses standard HTTP status codes and returns errors in a consistent format:
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded",
"details": {
"limit": 100,
"reset": 1234567890
}
},
"metadata": {
"requestId": "req_abc123",
"timestamp": "2026-07-27T12:00:00.000Z"
}
}Common Error Codes
Individual routes also emit codes outside this shared enum: the per-endpoint Errors lines on
this page name them (for example PROJECT_NOT_FOUND, PERMISSION_FORBIDDEN, the RFC 6749
{ error, error_description } shape on the gateway OAuth surface, and the lowercase Bouncer
codes such as validation_error and invalid_token).
SDKs & Packages
Official packages for integration:
See Choose Your Integration for detailed comparison.
Best Practices
- Cache API responses when possible to reduce API calls
- Use batch endpoints for bulk event tracking
- Implement exponential backoff for rate limit errors
- Store API keys securely and rotate them regularly
- Use middleware packages instead of raw API calls for detection
Support
- Email: kya+support@vouched.id
- Discord: Join our community