> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vouchmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust Badge

> A public, signed proof that a company is Vouchmark-verified.

The Trust Badge is a public artifact that turns a verification result into something a buyer can check from the verified company's website. It's a JWT — anyone with the token can confirm it came from Vouchmark and that the underlying record is still in good standing.

## Anatomy of a badge

A Trust Badge token carries:

* `vendorId` — the verified company's Vouchmark ID
* `band` — `verified`, `partially_verified`, or `self_asserted`
* `score` — the score at issue time
* `issuedAt` and `expiresAt` — badges are short-lived; refresh nightly
* `iss` — always `vouchmark.com`

The token is signed with `TRUST_BADGE_SECRET`, a key dedicated to badges (never reused for user authentication).

## Issuing a badge

A badge is issued automatically when a verified company hits a score threshold. You can also force a re-evaluation from the dashboard. Programmatically:

```bash theme={null}
curl https://api.vouchmark.com/v1/trust-badge/my-badge?vendorId=cmp_aBcD... \
  -H "Authorization: Bearer $TOKEN"
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "vendorId": "cmp_aBcD...",
    "customerId": "usr_aBcD...",
    "status": "active",
    "score": 90,
    "badgeToken": "eyJhbGciOiJIUzI1NiIs...",
    "issuedAt": "2026-05-12T00:00:00Z",
    "revokedAt": null,
    "expiresAt": "2026-05-13T00:00:00Z"
  }
}
```

`badgeToken` is only populated while `status` is `active`; once a badge is revoked it is `null`.

## Verifying a badge

Anyone — no auth — can verify a token:

```bash theme={null}
curl "https://api.vouchmark.com/v1/trust-badge/verify?token=eyJhbGciOiJIUzI1NiIs..."
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "valid": true,
    "vendorId": "cmp_aBcD...",
    "customerId": "usr_aBcD...",
    "score": 90,
    "status": "active",
    "issuedAt": "2026-05-12T00:00:00Z",
    "expiresAt": "2026-05-13T00:00:00Z"
  }
}
```

The endpoint always returns `200`; validity is expressed in `data.valid`. It validates the signature *and* checks the badge's status in the database. A badge that has been revoked (after a sanction hit, say, or a failed re-verification) returns `data.valid: false` with a `reason` — even though the JWT signature is intact.

## Embedding the badge

Drop this snippet on the verified company's website:

```html theme={null}
<a
  href="https://vouchmark.com/verify?token=YOUR_TOKEN"
  rel="noopener"
  target="_blank"
>
  <img
    src="https://vouchmark.com/badge/YOUR_TOKEN.svg"
    alt="Vouchmark Verified"
    width="160"
    height="48"
  />
</a>
```

The image URL is itself a verification: the SVG endpoint re-checks the token on every render, so a revoked badge renders as "expired" automatically.

<Warning>
  Don't hardcode the SVG into the page. The badge endpoint is the source of truth — fetch it live so revocations propagate.
</Warning>

## Revocation

Badges are revoked when:

* Smart Sentinel detects a material change (e.g. CAC status flipped to `INACTIVE`, sanction hit, FIRS TIN deactivated).
* The owner manually disables it from the dashboard.
* The underlying score drops below the issuing threshold on a nightly re-score.

Once revoked, the JWT still parses but the verify endpoint returns `valid: false`.