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

# Request a STIR/SHAKEN attestation letter

> When an attestation is requested (vendor or client tier), the GET/POST/DELETE endpoints behind the compliance attestation controller, the legal bind versus your statement of compliance, how the Trust Center evidence pack integrates it, how integrity (signed timestamp + hash) appears, and re-issue / rotation behavior.

# Request a STIR/SHAKEN attestation letter

Your tenant's attestation posture is the level (A, B, or C) your outbound
traffic signs at and the policy you declare for it. A vendor or client asks
for the attestation letter to see that declared posture plus the per-number
measurement — not a platform promise. This page walks the request sequence,
the endpoint family behind it, the split between the legal bind and your own
statement of compliance, the Trust Center integration, the integrity fields,
and re-issue behavior.

<Warning>
  This page describes your tenant's own attestation document. It is **not
  legal advice** — who demands the letter (a vendor's security review, a
  client's procurement tier, a regulator) and what satisfies them depends on
  your contracts. Confirm the specifics with qualified counsel.
</Warning>

## 1. When the attestation is requested

You generate this document when an external party asks for proof of the
posture your organization operates under — typically one of:

* **A vendor's vendor-review questionnaire** (a service you procured, asking
  how you attest outbound traffic).
* **A client tier** (a customer of yours, usually enterprise, asking the same
  as part of onboarding or annual review).
* **A regulator or auditor** working the same questionnaire your other
  compliance evidence surfaces already answer.

The request triages into two halves: the **policy** you declared, and the
**posture** that policy measured. Show both — the letter is the pair, never
one without the other.

## 2. Retrieve the attestation through the controller routes

All endpoints are under
`https://api.orbit.devotel.io/api/v1/compliance/attestation`. Policy writes
require workspace **owner** or **admin**; reads accept any authenticated
member.

**Read the policy you declared.**

```bash theme={null}
curl -s "https://api.orbit.devotel.io/api/v1/compliance/attestation/policy" \
  -H "X-API-Key: dv_live_sk_..."
```

**Read the posture snapshot.** Classifies every originating number against
that policy.

```bash theme={null}
curl -s "https://api.orbit.devotel.io/api/v1/compliance/attestation/posture" \
  -H "X-API-Key: dv_live_sk_..."
```

**Update the declared policy** (partial patch — absent fields keep their
current value). Owner/admin only.

```bash theme={null}
curl -s -X PUT "https://api.orbit.devotel.io/api/v1/compliance/attestation/policy" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "target_attestation": "A", "downgrade_handling": "monitor" }'
```

**Delegate certificate lifecycle.** BYON numbers upgraded to partial (B)
attestation sit under the delegate-certificate registry.

| Endpoint | Purpose |
| - | - |
| `GET /compliance/attestation/delegate-certs` | List this org's registered certificates. |
| `POST /compliance/attestation/delegate-certs` | Register a certificate (PEM, coverage list, validity window). |
| `DELETE /compliance/attestation/delegate-certs/:id` | Revoke a certificate (immediate; audit row survives). |

The response carries the policy + the measured posture together. Deliver
that composite to the requester; it is the attestation letter.

## 3. The legal bind versus your statement of compliance

STIR/SHAKEN attestation splits cleanly:

* **The carrier's legal bind.** The carrier of record that signs outbound
  traffic does so at exactly the level the platform attests, and no higher.
  That signing is a legal step the provider answers for — your policy never
  raises the level it signs at, and no policy form can turn a below-target
  flag into call handling. The concept page has
  [the ownership-first resolver](/compliance/attestation).
* **Your statement of compliance.** What you attest in the letter is the
  target and downgrade posture you declared and run against — owned by you
  and your counsel, recorded in your audit log. Orbit records and measures;
  the claim is yours.

Both halves stay truthful: the measured posture classifies what your traffic
actually attests at, and the declared policy is what the letter states. One
does not override the other.

## 4. Integrating with the Trust Center evidence pack

If the requester is a procurement team, fold this letter into the
[Trust Center evidence pack](/compliance/trust-center-evidence-pack) rather
than hand it over as a loose document. Generate the SOC 2, ISO 27001, or
GDPR binder; the attestation policy becomes one of the workspace-derived
rows your pack states verbatim, alongside the audit-ledger replay and
checksum. Point the recipient at the pack first, and only hand this letter
directly if their questionnaire bypasses the binder route.

## 5. Integrity — signed timestamp and hash

Every deliverable carries two integrity cues:

* **Timestamp.** Each successful policy write is written to your audit log
  (`compliance.attestation.policy_updated`), and each delegate-cert
  register/revoke writes its own audit row. The recipient reads the ISO
  timestamp bounded by that audit event — that is the **signed timestamp**,
  the one the posture snapshot agrees with at the moment you captured it.
* **Checksum / hash.** When the letter travels inside a binder, the binder's
  `download_sha256` field is the byte-level checksum the recipient re-hashes
  the file against. If you hand only the JSON response, preserve the raw
  bytes — a recipient re-hashing the JSON body verifies it matches.

Never redact either. The integrity pair (audit timestamp + checksum) is what
moves the letter from "a claim you wrote" to "a claim a recipient can verify
byte-for-byte."

## 6. Re-issue and rotation behavior

A letter you already issued stays valid; rotation is about issuing the next
one over a stable audit baseline.

* **Policy update** — a PUT writes the new singleton; the old declared
  posture is superseded in-place. Old letters keep their own audit row; the
  new letter names its own.
* **Delegate certificate renewal** — register a renewed chain **before** the
  validity window closes (the derived status flips from `active` to
  `pending`/`expired`/`revoked` live, at which point covered numbers revert
  to ownership-based level). Re-issue the letter once the renewed chain is
  active.
* **Revocation** — cannot be undone; a revoked certificate's numbers revert
  to the ownership-based level immediately. Re-issue so the recipient sees
  the current coverage set.

Generate the next letter as soon as the change lands, and let the
[Trust Center evidence pack](/compliance/trust-center-evidence-pack) cadence
handle the rest.

## See also

* [STIR/SHAKEN attestation posture](/compliance/attestation) — the concept
  page: ownership resolver, policy levers, posture snapshot.
* [Trust Center evidence pack](/compliance/trust-center-evidence-pack) —
  the binder generator this letter slots into.
* [Delegate certificate route family](/api-reference/endpoints/compliance) —
  the compliance API reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.