Skip to main content

​
STIR/SHAKEN attestation posture

STIR/SHAKEN attaches a cryptographic signature to every outbound call, rated at one of three attestation levels — A (full), B (partial), or C (gateway) — and receivers use that level to weigh robocall risk before they render the call. This page is the single concept reference for how your tenant’s attestation posture works: what feeds the level, the two policy levers you declare, the posture snapshot that measures against them, and how to close a gap. The scattered how-to material this page consolidates lives at the voice-channel page, the attestation model concept page, and the downgrade troubleshooting guide; everything here is cross-checked against the public endpoints so you can hunt-and-verify each claim.
This page describes your tenant’s own attestation controls. It is not legal advice, and Orbit neither mandates a target level for you nor guarantees any particular STIR attestation — the carrier of record signs outbound traffic, and it will not sign higher than the platform attests. The policy and statuses you set here drive reporting; they never gate or reroute a call.

​
1. Ownership-first, BYON-upgradeable

The level a call signs at is resolved at dial time from number ownership, before any policy is consulted. The resolver walks a fixed order of ownership:
  • Owned number → A (full). A caller ID that is an active number your organization owns through Orbit — purchased or ported in and billed to your org — attests A. Ownership is the only path to full attestation.
  • Leased pool number → B (partial). A caller ID that is a pool number with an active assignment to your org attests B. The platform can authenticate your org, but pool ownership is not your verified right-to-use.
  • Anything else → C (gateway). A verified external caller ID, a hosted or bring-your-own number (BYON) you legitimately control but do not own in Orbit, or an unattributable caller ID attests C — the weakest signal, and the one downstream carriers most often shade as spam.
BYON numbers are the upgradeable exception. Under ATIS-1000092 (the industry’s delegated-attestation standard), your service provider hands you a delegate certificate authorizing specific numbers; registering that certificate with Orbit lifts the numbers it covers from C to B — partial, never full. The parity matters: the certificate is a tenant-supplied artifact, its chain is not cryptographically validated by the platform, and the covered-number list you record with it is free-form input not bound to the certificate’s real TNAuthList. B — “customer authenticated, number authorization not provider-verified” — is the correct ceiling for that evidence, and it is deliberate: a self-registered artifact must never be able to spoof full attestation for arbitrary numbers. The same resolver honors the certificate lifecycle live: a certificate that is registered but not yet valid, past its validity window, or revoked stops covering its numbers, and those numbers fall back to their ownership-based level at the next call. Resolution fails open to C. If the ownership lookups behind level resolution fail (a database error, an unresolvable caller ID), the call still places — signalled at C rather than blocked — because a recoverable reporting downgrade beats a blocked call.

​
2. The tenant’s two policy levers

Only workspace owners and admins can write the policy; any authenticated member can read it. Both levers, plus two reporting flags, are one singleton record per organization. Lever one — the outbound target, with its downgrade handling: Lever two — the inbound verification floor, with the spoof-risk flag: Both levers behave the same way operationally:
  • GET /compliance/attestation/policy always returns 200 with a full policy object — an org that has never set one gets the safe defaults above, so a reader never has to distinguish “unset” from an error.
  • PUT /compliance/attestation/policy is a partial patch: absent fields keep their current value, so { "target_attestation": "A" } alone never touches your inbound floor. A successful write lands in your audit log; invalid values return 422 VALIDATION_ERROR.
The persistence model matches the patch semantics. The policy lives on your organization’s settings under its own key (stir_shaken_attestation_policy), and each write updates only that key — a write here never rewrites the whole settings object, so it cannot clobber a concurrent writer on another settings key. Delegate certificates sit on their own sibling key (stir_shaken_delegate_certificates) with the same one-key-per-write discipline.

​
3. Technical posture snapshot

GET /compliance/attestation/posture is the read-only measurement: it classifies what your traffic actually attests at against the levers you declared. It answers two questions in one call. Originating: who is below the declared target. The snapshot enumerates every number you originate from — your owned numbers plus your active pool leases, with the stronger owned attribution winning if a number appears both ways — and stamps each with the level the resolver applies, owned → A and leased → B, plus a meets_target verdict against your target_attestation. A totals row aggregates the same into counts of numbers meeting target, below target, and the per-level split (A/B/C). The per-number table is capped at 500 rows (numbers_truncated flags the cap), so a sender running thousands of DIDs sees the totals first and the specific held-back identifiers next — not an aggregate with the offender hidden inside it. Inbound: Identity-header aggregation against the floor. The same payload carries a 30-day summary of inbound calls that arrived on DIDs your org owns, classified against your inbound_min_verification floor: signed calls at or above the floor count as verified; signed-below-floor and off-net calls count as unverified; failed and unsigned calls count as spoof_risk when your flag is on, otherwise they fall into unverified. verified_rate is the verified share of all inbound calls — or null, not zero, when there was no inbound traffic in the window, so “no calls” never reads as “0% verified.” Both halves are scoped to your organization. Originating rows come from your own numbers and assignments only; the inbound half counts calls that arrived on a DID currently assigned to your org, and a released DID that is reassigned to a new owner starts that owner’s inbound history clean — you never inherit the prior owner’s verification summary. Reads fail soft: if an underlying lookup is unavailable, the affected half returns empty or zeros rather than failing the snapshot. The snapshot is point-in-time — where the posture stands when you read it. For the trajectory, the two attestation-analytics endpoints roll up the same org-scoped traffic over 24h to 90d: the outbound A/B/C mix with per-tier answer-rate lift and downgrade causes (GET /numbers/attestation-analytics), and the inbound attestation mix with the spoof-risk breakdown (GET /numbers/inbound-attestation-analytics). Step 7 of the posture guide walks both endpoints, including how to read a lapsed delegate certificate off the trend.

​
4. How to build a verified-number set

The posture snapshot names the gap; this is the order of ownership that closes it. Work top-down — the earlier rung is the stronger instrument.
  1. Own the numbers (the only path to A). Purchase or port the DIDs into Orbit so your org owns them outright, then move outbound traffic onto them. Re-read the posture snapshot: those numbers resolve to A and the below-target count closes. Run this certification step for any order of ownership — a port-in, a new purchase, or moving existing traffic — the posture read is how you confirm the level actually moved.
  2. Upgrade BYON with delegate certificates (C → B). For numbers you control but do not own in Orbit, obtain the delegate certificate chain (PEM) from your service provider per ATIS-1000092, then register it with its coverage list and validity window:
  1. Watch the certificate lifecycle. Covered numbers attest B only while the certificate’s effective status is active — the registry derives the status live, so pending (valid-from still ahead), expired (past valid-until), and revoked each mean the numbers have already fallen back to their ownership-based level. List the registry (GET /compliance/attestation/delegate-certs), and re-register a renewed chain before the window closes — the flip is when the drop happens, not after. Revocation (DELETE /compliance/attestation/delegate-certs/:id) is immediate and cannot be undone; the record is kept with a revoked-by line for audit.
  2. Set a target your set can reach. If the snapshot persists in showing leased (B) or uncovered BYON (C) numbers against an A target, either cover the numbers (rungs 1–2) or accept a B target until coverage changes:
A policy write can only restate your target and floors — no policy value raises the level a number signs at. The softswitch signs exactly the level the platform attests, so the gap always closes at ownership and certificate coverage, never at the policy form.

​
5. Posture-agreement with the regulatory frame

These controls are yours to run, not Orbit’s to impose. You pick the target, the downgrade handling, the inbound floor, and the certificate coverage. Orbit records the policy, classifies your traffic against it, and derives effective certificate status — it mandates no level, and it guarantees no STIR attestation outcome. That division is deliberate and holds across the platform’s compliance frame: attestation posture is tenant-owned, never a platform screen. The carrier of record signs at exactly the level the platform attests and no higher, so no policy value, gate, or reroute can turn a below-target flag into call handling. Regulatory judgement about which level a given programme must hold — which traffic should run at A, which floors to enforce — stays with you and your counsel, on your audit ledger.