Customer integration — API keys, endpoints and the TypeScript SDK

AgentAudit exposes four public HTTPS endpoints that your agent runtime and CI pipeline call. All four accept the same tenant-scoped ingestion key — no session, no OAuth handshake, no per-call refresh. The key resolves to your workspace; RLS keeps every write and read scoped to that tenant.

The endpoints are: POST /api/public/telemetry for traces and outcomes; POST /api/public/evaluations for CI-reported evaluation runs; POST /api/public/audit for append-only compliance records; and POST /api/public/governance/promotion-check as a synchronous deployment gate. Base URL is https://agentauditcentral.co.uk.

Ingestion keys are minted from Portal → Administration → Ingestion keys. The full key is shown exactly once at mint time. Only a SHA-256 hash is stored on our side; if you lose the plaintext, rotate the key rather than trying to recover it.

Format: aa_live_<12-hex-prefix>.<base64url-secret>. The prefix is visible to admins and lets you identify which key is being used at ingestion time; the secret is the part we never store.

Send it as an Authorization: Bearer header. As a fallback, X-AgentAudit-Key is also accepted. Never embed it in a browser bundle — keep it in your secrets manager and inject it as an environment variable in the agent runtime and CI job.

• Authorization: Bearer aa_live_ab12cd34ef56.k3Y_S3cReT…
• Content-Type: application/json
• Endpoints are same-origin CORS from your server-side runtime — no preflight needed for server-to-server calls.

Telemetry: single or batch. Batch shape is { events: [...] } with up to 200 events per call.

curl -X POST https://agentauditcentral.co.uk/api/public/telemetry \ -H 'Authorization: Bearer aa_live_…' -H 'Content-Type: application/json' \ -d '{"trace_id":"t-8f2","outcome":"success","latency_ms":812,"tool_count":3,"agent_id":"…"}'

Evaluations: called from CI at the end of a harness run.

curl -X POST https://agentauditcentral.co.uk/api/public/evaluations \ -H 'Authorization: Bearer aa_live_…' -H 'Content-Type: application/json' \ -d '{"name":"billing-refund-harness","status":"passing","pass_rate":96.4,"agent_id":"…"}'

Audit: append-only. Each row is SHA-256 hash-chained to the previous audit row in your tenant; the response returns the new row_hash so your runtime can log a proof of inclusion.

curl -X POST https://agentauditcentral.co.uk/api/public/audit \ -H 'Authorization: Bearer aa_live_…' -H 'Content-Type: application/json' \ -d '{"actor":"agent://billing-copilot","action":"refund.issued","subject":"case-1194","rationale":"Consumer Duty foreseeable harm avoided","framework":"FCA-CD"}'

Promotion check: synchronous gate. Returns { allowed: true|false, reason, evaluation } so your CI can block a deploy in a single line.

curl -X POST https://agentauditcentral.co.uk/api/public/governance/promotion-check \ -H 'Authorization: Bearer aa_live_…' -H 'Content-Type: application/json' \ -d '{"agent_id":"…","min_pass_rate":90,"max_age_hours":72}'

Download the SDK from /sdk/agentaudit.ts and drop it into your project. It has zero runtime dependencies, works on Node 18+, Deno, Bun, and Cloudflare Workers, and batches telemetry emits by default.

import { createAgentAudit } from './agentaudit'; const aa = createAgentAudit({ apiKey: process.env.AGENTAUDIT_KEY! }); await aa.telemetry.emit({ trace_id, outcome: 'success', latency_ms: 812 }); await aa.evaluations.report({ name: 'billing-refund-harness', status: 'passing', pass_rate: 96.4 }); const gate = await aa.governance.promotionCheck({ agent_id, min_pass_rate: 90 });

The SDK exposes four namespaces — telemetry, evaluations, audit, governance — matching the endpoints one-to-one. Call aa.close() before process exit to flush the batch buffer.

Rotate a key from Portal → Administration → Ingestion keys → Rotate. Rotation issues a new secret under the same key record; the old secret is invalidated immediately. Update your secrets manager and redeploy the runtime.

Every mint, rotation, scope change and revocation is recorded in a per-tenant audit trail visible on the same page. Only admins in your workspace can see it; the backend service is the only writer.

The promotion-check endpoint enforces the no-eval = no-promote rule. Wire it into your CI as a required step after your build succeeds and before the production deploy job. If it returns { allowed: false }, fail the job and surface the reason in the check output — 'no_recent_evaluation', 'evaluation_not_passing', or 'pass_rate_below_threshold' each map to a clear engineering action.

Defaults are conservative: 80% pass rate, 72-hour freshness window. Override per-agent by passing min_pass_rate and max_age_hours in the request body. High-risk agents typically raise the threshold to 95% and shrink the window to 24 hours.