# Trusta Developer Portal

Trusta exposes its trust data and verification infrastructure through a public
REST API, an OpenAPI 3.1 specification, an MCP server for AI agents, and a CLI.
Everything below is machine-readable and reachable without contacting us first —
no sales call, no sandbox request, no API key for published trust data.

## Machine-readable index

- [`https://trusta.dev/openapi.json`](https://trusta.dev/openapi.json) — OpenAPI 3.1 specification (mirrored at [`api.trusta.dev/openapi.json`](https://api.trusta.dev/openapi.json))
- [`/.well-known/api-catalog`](https://trusta.dev/.well-known/api-catalog) — RFC 9727 API catalog
- [`/.well-known/mcp.json`](https://trusta.dev/.well-known/mcp.json) — MCP server manifest
- [`/.well-known/mcp/server-cards.json`](https://trusta.dev/.well-known/mcp/server-cards.json) — MCP server card
- [`/.well-known/oauth-authorization-server`](https://trusta.dev/.well-known/oauth-authorization-server) — OAuth 2.0 authorization server metadata
- [`/.well-known/ai-plugin.json`](https://trusta.dev/.well-known/ai-plugin.json) — agent plugin descriptor
- [`/llms.txt`](https://trusta.dev/llms.txt) — site index for language models
- [`/agent-instructions.md`](https://trusta.dev/agent-instructions.md) — when to use Trusta and how to call it
- [`/setup.md`](https://trusta.dev/setup.md) — agent-followable setup guide

Every documentation page on this site is also available as Markdown. Send
`Accept: text/markdown` to any page URL, or append `.md`.

## API reference

Base URL: `https://api.trusta.dev`. All responses are JSON unless stated
otherwise. All timestamps are RFC 3339 UTC.

### Public endpoints (no authentication)

| Endpoint | Returns |
| --- | --- |
| `GET /trust/{projectSlug}` | published trust profile, wrapped in a `{ profile }` envelope |
| `GET /trust/{projectSlug}/trust.json` | the same profile as a bare JSON document |
| `GET /trust/{projectSlug}/controls` | controls with state, confidence, and evidence freshness |
| `GET /trust/{projectSlug}/signals` | latest signal detection, with commit and timestamp |
| `GET /trust/{projectSlug}/setup.md` | Markdown setup guide scoped to one project |
| `GET /trust/domains/{domain}` | trust profile resolved from a verified custom domain |
| `GET /public/trust/{orgSlug}` | organization trust center |
| `GET /openapi.json` | this API's OpenAPI 3.1 specification |
| `GET /health` | liveness probe, `{"status":"ok"}` |

### Authenticated endpoints

Workspace management — organizations, projects, controls, evaluations,
publishing, custom domains, collectors, and evidence ingest — requires a bearer
token. Every operation, its parameters, and its response schema is described in
[`/openapi.json`](https://trusta.dev/openapi.json), which is the authoritative
reference.

## Quickstart

```bash
# a company's live trust profile
curl https://api.trusta.dev/trust/yourcompany

# the bare machine-readable trust state
curl https://api.trusta.dev/trust/yourcompany/trust.json

# resolve a vendor from their trust domain
curl https://api.trusta.dev/trust/domains/trust.yourcompany.com

# ask this site for Markdown instead of HTML
curl -H 'Accept: text/markdown' https://trusta.dev/developers
```

### Response shape

```json
{
  "profile": {
    "schemaVersion": 1,
    "project": { "slug": "yourcompany", "name": "Your Company" },
    "version": 42,
    "publishedAt": "2026-08-22T09:12:44.000Z",
    "summary": { "...": "aggregate control state" },
    "controls": [
      {
        "key": "mfa_enforced",
        "category": "access",
        "name": "MFA enforced for all developers",
        "state": "pass",
        "confidence": "high",
        "latestEvidenceAt": "2026-08-22T08:55:10.000Z",
        "freshUntil": "2026-08-23T08:55:10.000Z",
        "nextCheckAt": "2026-08-22T20:55:10.000Z"
      }
    ]
  }
}
```

Trust state is computed deterministically from signals. Two callers reading the
same publication version always see the same controls in the same state — there
is no model in the evaluation path.

### Errors

Errors use a stable envelope: `{ "error": { "code": "...", "message": "..." } }`.
Public reads return `404` when a project slug or verified domain is unknown, or
when the project has never been published. Authenticated calls return `401` when
the token is missing or invalid and `403` when the caller has no access to the
resource.

### Rate limits and caching

Published trust reads are served from cache with
`Cache-Control: public, s-maxage=300`. Poll no more than once per minute per
project — trust state changes when collectors publish, not when you ask. There
is no per-key quota on public reads today; if you need a higher sustained
volume, tell us at <hello@trusta.dev> before you start.

## MCP server

Trusta exposes an MCP (Model Context Protocol) server at
`https://api.trusta.dev/mcp` over Streamable HTTP transport. This lets Claude,
ChatGPT, Cursor, and other agents call Trusta natively. The manifest is
published at [`/.well-known/mcp.json`](https://trusta.dev/.well-known/mcp.json)
and as an MCP server card at
[`/.well-known/mcp/server-cards.json`](https://trusta.dev/.well-known/mcp/server-cards.json).
No authentication is required — the server exposes published trust data only.

Available tools:

- `get_trust_profile` — published trust profile by project slug
- `get_trust_controls` — controls and evidence for a project
- `get_trust_signals` — signals with timestamps
- `get_trust_json` — machine-readable trust state

```json
{
  "mcpServers": {
    "trusta": {
      "type": "http",
      "url": "https://api.trusta.dev/mcp"
    }
  }
}
```

## Authentication

Public trust endpoints require no authentication. Everything else uses one of
two credentials:

- **Human users:** Cognito OAuth 2.0 (`authorization_code` grant), used by the dashboard
- **Machine clients and collectors:** hashed bearer secrets (`client_credentials` grant)

OAuth 2.0 endpoints:

- Authorization: `https://auth.trusta.dev/oauth2/authorize`
- Token: `https://auth.trusta.dev/oauth2/token`
- Server metadata: [`/.well-known/oauth-authorization-server`](https://trusta.dev/.well-known/oauth-authorization-server)

A collector secret is returned exactly once, at creation or rotation. It is
stored hashed and cannot be read back — capture it immediately and put it in
your CI secret store.

## CLI

The [`trusta` npm CLI](https://www.npmjs.com/package/trusta) connects
infrastructure, pushes evidence, and manages collectors from a terminal or a CI
job.

```bash
npm install -g trusta
trusta --help
trusta init
```

`trusta init` detects the GitHub repository, creates a collector credential, and
prints a ready-to-paste GitHub Actions snippet. The full walkthrough is in
[`/setup.md`](https://trusta.dev/setup.md), written so a coding agent can follow
it unattended.

## Support

- Integration questions: <hello@trusta.dev>
- Suspected vulnerabilities: [security policy](https://trusta.dev/security)
- Everything else: [contact](https://trusta.dev/contact)