Authentication and keys

Quickstart

Example request

# Reads a company's published Trust Profile by its domain. No key, no account.curl -s "https://trooth.co/api/network/profile?q=your-co.com&contract=2"

const res = await fetch("https://trooth.co/api/network/profile?q=your-co.com&contract=2");const record = await res.json();if (record.found) console.log(record.name, record.domain);

Authentication and rate limits

Authorization model

The Trooth application programming interface (API) at api.trooth.co accepts four kinds of customer credential. Sessions, bound API keys and scoped tokens are sender-constrained with Demonstrating Proof of Possession (DPoP, RFC 9449): each is accepted only together with a fresh proof signed by the private key it is bound to. A copy of the credential alone, taken from a log, a proxy, a crash report or a leaked environment, is refused.

The credentials

• Session token. Minted when a person signs in and held in an httpOnly, Secure, SameSite=Lax cookie on trooth.co, where page scripts cannot read it. api.trooth.co accepts it only from trooth.co's own server, with a proof signed by trooth.co's server key. Sent from anywhere else, as a bearer or with any other key's proof, it is refused. It lasts 30 days at most and is revoked from Account security.

• Workspace API key (tk_live_). Created by a member of the workspace with a confirmed address, and stored only as a SHA-256 hash. A key created with dpop_jkt, the RFC 7638 thumbprint of your public key, is bound to that key: only its proofs are accepted, everywhere, and a plain bearer is refused. A key created without one is an ingest key: it reaches one endpoint, POST /v1/evidence/webhook, which appends an evidence event your company asserts about itself, so a tool that cannot sign a proof can still report. An ingest key reads nothing and changes nothing else. Revocation takes effect on the next request.

• Scoped token (st_). Minted by a full credential for one named operation, for 15 to 60 minutes, to hand to an agent, and bound at mint to the agent's key: dpop_jkt is required.

• OAuth access token (Model Context Protocol and Agent2Agent). Issued by Trooth's authorization server for exactly one resource, https://api.trooth.co/public/mcp or https://api.trooth.co/a2a/v1 (RFC 8707 audience, RFC 9728 metadata). It reaches the read-only Model Context Protocol tools and the Agent2Agent tasks its own subject created. When the authorization server binds the token to a key (the cnf.jkt claim), that key's proof is required and a plain bearer is refused. A token issued unbound is a bearer token, limited to its audience and lifetime and to reading the signed-in workspace's own record.

Trooth's own operations (the operator key, scheduled jobs, webhook signatures) use separate headers or signatures, are never customer credentials, and resolve no workspace.

The proof

Send the token in the Authorization header with the DPoP scheme, and one proof in the DPoP header, new for every request. The proof is a JSON Web Signature (JWS) with:

• header typ dpop+jwt, alg ES256 or EdDSA, and your public key in jwk, with no private member;
• claims htm (the request method), htu (the request URL without query or fragment), iat (now; accepted from five minutes before to one minute after the API's clock), a unique jti, and ath, the base64url SHA-256 of the access token.

A proof is accepted once: its jti is remembered for ten minutes, and a second use is refused. A refusal answers 401 with WWW-Authenticate: DPoP and an error of dpop_required, invalid_dpop_proof or invalid_token.

// npm i jose   (any JOSE library that signs ES256 or EdDSA works)import { generateKeyPair, exportJWK, calculateJwkThumbprint, SignJWT } from "jose";import { createHash, randomUUID } from "node:crypto";// Make the key once and keep the private half where your client runs.const { publicKey, privateKey } = await generateKeyPair("ES256");const jwk = await exportJWK(publicKey);const dpopJkt = await calculateJwkThumbprint(jwk); // send as dpop_jkt when you create the API keyasync function call(method, url, token, body) {  const u = new URL(url);  const proof = await new SignJWT({    htm: method,    htu: u.origin + u.pathname,    jti: randomUUID(),    ath: createHash("sha256").update(token).digest("base64url"),  })    .setProtectedHeader({ typ: "dpop+jwt", alg: "ES256", jwk })    .setIssuedAt()    .sign(privateKey);  return fetch(url, {    method,    headers: {      authorization: `DPoP ${token}`,      dpop: proof,      "content-type": "application/json",      ...(method === "GET" ? {} : { "idempotency-key": randomUUID() }),    },    body: body ? JSON.stringify(body) : undefined,  });}const apiKey = process.argv[2]; // the bound key, passed in from your secret store, never in sourceconst res = await call("POST", "https://api.trooth.co/v1/evidence/webhook", apiKey, {  evidence_type: "runtime_log",  summary: "Nightly guardrail policy enforcement",  status: "observed",  source: "your-tool",});if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

Tenant isolation

The workspace a request acts on comes from its credential and nothing else: never from a header, a path, a query parameter or a body. Every database read and write is bound to that workspace. Before each release the isolation suite runs against the Worker that serves the API, with two workspaces and a client holding copies of one workspace's tokens; a release with a failing assertion does not deploy.

Idempotency

Every POST, PUT, PATCH and DELETE accepts an Idempotency-Key header of 8 to 255 printable characters. The first request with a key runs and its answer is kept for 24 hours; the same key with the same request returns that answer with Idempotency-Replayed: true and runs nothing; the same key with a different request is refused with 422; a key whose first request is still in progress answers 409. A 5xx, 401, 403, 408, 409, 425 or 429 answer is not kept, so a retry runs again. Keys belong to the credential that sent them, and a kept answer is encrypted under a key derived from that credential and the request.

Audit log and export

Each workspace's audit log holds its sign-ins, password, two-factor and address changes, API keys, every write made with one of its credentials (method, path, status, which credential, whether it was a replay) and every refused attempt to use one of its credentials without the proof it is bound to. No token and no request body is written. Download the whole log from Audit log in the workspace as CSV or JSON Lines, oldest first, 5,000 rows a file.

What this does not cover

• A session cookie stolen out of a browser still works in a browser at trooth.co until it expires or is revoked. Binding the browser itself to a key is not yet in place.
• An OAuth access token the authorization server issues unbound remains a bearer token for its lifetime.
• An ingest API key is a bearer credential for its one endpoint: a stolen copy can append self-asserted evidence events to the workspace until the key is revoked, and each one is in the audit log. A key created with dpop_jkt has no such use.

MCP server for AI agents

{  "mcpServers": {    "trooth": {      "type": "http",      "url": "https://api.trooth.co/public/mcp"    }  }}

Every interface, in one table

A summary of the supported interfaces. The controlling list, with each one's access, side effects, limits and availability on this deployment, is /interfaces.json. Anything not listed there is internal, unsupported and may change without notice.

Pagination and completeness

Directory search: pass next_cursor back as cursor until null. A cursor is a position in a live list, not a snapshot, so a walk is best-effort discovery and not a consistent full export.

Walks are not atomic: mid-walk changes may appear later or be passed over. No tombstones; removed companies are absent.

To hold a complete copy:

1. Walk to the end twice and compare slug sets.
2. In both walks: current. Only in the second: new.
3. Only in the first: removed or unpublished; GET /api/network/profile?q=<slug> confirms with found: false.
4. Repeat until two walks agree.

An unreadable cursor gets 400, never an empty page.

The API is free.

Every endpoint, joining, listing and witnessing are free. Nothing is for sale, including any position on any Trooth page.

Read the full API reference.