Developers

Trusta Developer Portal

This page has one main job: get your own project's infrastructure connected to Trusta — the CLI, the collector GitHub Action, and the collector API that feeds your trust page. Everything below that is secondary: the public REST API and MCP server for anyone reading published trust data, not publishing it.

Connect your infrastructure

Run this in your project root. The CLI signs you in, auto-detects the GitHub repo, creates a collector credential, and prints a ready-to-paste GitHub Actions snippet:

npx trusta init

It prints three things — save all of them:

  • A collector secret, for TRUSTA_COLLECTOR_SECRET in your CI secrets
  • A GitHub Actions YAML snippet, for a workflow file
  • The URL your trust page will live at once you publish it

What the GitHub Action does

Save it as .github/workflows/trusta.yml. It sends a heartbeat and reports build provenance as evidence on every push to main, plus every six hours so a stale collector is visible even between deploys:

name: Trusta Trust Signal
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 */6 * * *'

jobs:
  trusta-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Heartbeat
        run: |
          curl -s -X POST https://api.trusta.dev/collectors/${{ vars.TRUSTA_COLLECTOR_ID }}/heartbeat \
            -H "Authorization: Bearer ${{ secrets.TRUSTA_COLLECTOR_SECRET }}" \
            -H "Content-Type: application/json" \
            -d '{"sourceRef":"${{ github.sha }}"}'

      - name: Report build provenance
        run: |
          curl -s -X POST https://api.trusta.dev/ingest/evidence \
            -H "Authorization: Bearer ${{ secrets.TRUSTA_COLLECTOR_SECRET }}" \
            -H "Content-Type: application/json" \
            -d '{
              "projectId": "${{ vars.TRUSTA_PROJECT_ID }}",
              "evidenceType": "build_provenance",
              "sourceType": "github_actions",
              "sourceRef": "${{ github.sha }}",
              "observedAt": "${{ github.event.head_commit.timestamp }}",
              "payload": {
                "workflow": "${{ github.workflow }}",
                "runId": "${{ github.run_id }}",
                "actor": "${{ github.actor }}"
              }
            }'

After the first run, go to app.trusta.dev/app and click Publish. Your trust page goes live at https://trust.trusta.dev/{your-project-slug}.

Or hand it to an agent

/setup.md is a self-contained, copy-pasteable prompt for Claude Code, Cursor, Windsurf, or Codex — it runs trusta init, wires the secrets, adds the workflow file, and pushes. You do not need to read the YAML above to use it.

Collector API

What the workflow above is actually calling. Both require Authorization: Bearer {collectorSecret}:

  • POST /collectors/{collectorId}/heartbeat — proves the collector is still alive
  • POST /ingest/evidence — reports one piece of evidence for a control
  • POST /ingest/evidence/batch — reports several at once

Once your project exists, its own setup guide has your real project ID and collector ID pre-filled: https://api.trusta.dev/trust/{your-project-slug}/setup.md.

Embed it

Drop a live trust badge in your README with trusta:

[![Trust Score](https://app.trusta.dev/api/badge/{projectSlug})](https://trust.trusta.dev/{projectSlug})

Or render live trust status inside your own app with @trusta/react, which ships with no runtime dependencies of its own — React is a peer:

import { TrustCenter } from '@trusta/react';

<TrustCenter org="your-org" />;

Reading published trust data

Everything from here down is for the other direction — a buyer's tooling, a procurement system, or an AI agent reading a company's published trust page, not setting one up. It is all machine-readable and reachable without contacting us first — no sales call, no sandbox request, no API key for published trust data.

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

Public endpoints (no authentication)

  • GET /trust/{projectSlug} — published trust profile for a project, wrapped in a { profile } envelope
  • GET /trust/{projectSlug}/trust.json — the same profile as a bare JSON document, for direct machine consumption
  • GET /trust/{projectSlug}/controls — published controls with state, confidence, and evidence freshness
  • GET /trust/{projectSlug}/signals — the latest signal detection, with the commit and timestamp it came from
  • GET /trust/{projectSlug}/setup.md — Markdown setup guide scoped to one project
  • GET /trust/domains/{domain} — resolve a trust profile from a verified custom domain
  • GET /public/trust/{orgSlug} — organization trust center listing every published project
  • GET /openapi.json — this API's OpenAPI 3.1 specification
  • GET /health — liveness probe, returns {"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, which is the authoritative reference.

Quickstart

Read a company's live trust profile with a single unauthenticated request:

curl https://api.trusta.dev/trust/yourcompany

Fetch the bare machine-readable trust state:

curl https://api.trusta.dev/trust/yourcompany/trust.json

Resolve a vendor when all you know is 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

A published trust profile carries the project, a monotonically increasing publication version, the publishedAt timestamp, a summary, and the controls:

{
  "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 and as an MCP server card at /.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

Add it to a Claude Code or Cursor MCP configuration:

{
  "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:

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.

Machine-readable index

Every developer resource lives at a predictable URL:

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

Support

Integration questions: hello@trusta.dev. Suspected vulnerabilities: security policy. Everything else: contact.

← Back to homepage