Skip to main content

​
Trusted Account Signal

A Trusted Account is a third-party account a BotShield user has linked inside an active, Face-ID-gated BotShield session. PayPal, Coinbase, LinkedIn, X, GitHub, Reddit, and Instacart are supported in v2; banks (via Plaid) are on the v2.1 roadmap. Trusted Accounts strengthen the user’s MultiPass — they extend how long a verdict: pass lasts between Face ID prompts. They do not change the verdict semantics or what your server sees. The decision contract remains the v2 4-field shape (event_id, request_id, verdict, reason).

​
The Two Account Classes

v2 introduces a graded classification driven by what the third-party provider’s authentication actually verifies.

Class A — Identity-verified

The provider validates real-world identity (KYC, payment-rail anchored). Examples: PayPal, Coinbase. Future: banks via Plaid integration. Higher per-account weight in the freshness math, larger aggregate cap.

Class B — Ownership-only

The provider validates account control, not identity. Examples: LinkedIn, X, GitHub, Reddit, Instacart. Lower per-account weight, lower aggregate cap. Used in combination with Class A or with a long streak to reach durable thresholds.
The class is decided at link time and is immutable for the life of that linkage record. If BotShield reclassifies a provider in a future release, existing records keep their original class; only new linkages get the new classification.

​
What Trusted Accounts Do

Class A and Class B counts feed BotShield’s Path 1 freshness math. They extend the MultiPass TTL window — the number of hours a single Face ID event keeps the user in verdict: pass for standard scopes. 
ttlHours = streakTtlHours
         + classABoost(matureClassACount)
         + classBBoost(matureClassBCount)
ttlHours = min(ttlHours, 168)        // 7-day hard ceiling
Where streakTtlHours = streakMultiplier(consecutivePresenceDays) × 24.
1st mature account2nd3rd+ eachCap
Class A+24h+12h+6h+48h
Class B+12h+6h+3h+24h
A Trusted Account counts toward the boost only after a 14-day maturity gate — the linkage must exist for at least two weeks before it contributes. This is anti-farming defense: registering an account, linking it, and discarding the platform login does not buy a partner’s BotShield user a longer TTL window.

​
What Trusted Accounts Do NOT Do

Trusted Accounts do not appear in any partner-facing field. The decision contract is unchanged:
  • They do not affect the partner-visible verdict value
  • They do not affect the partner-visible reason enum
  • They do not appear in the sdk/verify-token JWT claims
  • They do not appear in webhook payloads
  • They do not affect the user-facing Human Presence tier on the Account tab (App Spec line 236 — “Trusted Accounts have zero effect on tier”)
Their entire effect is on ttlHours, which determines how often a multipass_active reason flips to multipass_stale for the user. Partners observe this only as the frequency at which verdict: require_presence fires for known users.

​
Path 1 vs Path 2

The two signal paths are an internal implementation detail — both produce the same v2 4-field response. They are not surfaced to partners as separate response variants.
1

Path 1 — Hardware-backed Presence (default)

Face ID / Secure Enclave event within the TTL window. The TTL is computed per the math above (streak multiplier × 24 + Class A boost + Class B boost, capped at 168h).
2

Path 2 — Trusted Account match

When the querying platform itself is a linked Trusted Account for this user (active row in verified_accounts), the linkage is the proof. No TTL evaluation. Returns verdict: pass with reason: multipass_active.Path 2 still respects the BotShield-absence circuit breaker: if the device credential has been deleted, Path 2 collapses too.

​
Why Path 2 Does Not Compromise the Security Model

​
The verification event already happened

When a user linked a Trusted Account, the OAuth flow ran inside an active BotShield session that required Face ID to establish. By the time the user authorized the connection to PayPal or LinkedIn, BotShield had already attested that a real verified human was on that device. The linkage record carries the timestamp of that verification event. The standing boolean from account match is attesting to that moment — not to continuous presence, but to a verified human deliberately authorizing this relationship.

​
BotShield is not trusting the platform’s auth method

A user may type a username and password to authorize their PayPal connection. This does not weaken the signal. BotShield is not trusting PayPal’s authentication method — BotShield is trusting its own Face-ID-gated session that preceded the OAuth flow. When a platform uses passkeys for its own authentication, both ends of the linkage are hardware-backed. This is a stronger combined proof, but the security guarantee does not depend on it.

​
The attack vector is closed

An attacker who compromises a user’s PayPal credentials cannot use that access to generate a BotShield signal. To establish or modify a Trusted Account linkage, they would need to be inside an active BotShield session that required Face ID on the user’s registered device. The attack cannot be mounted from the platform side in.

​
The circuit breaker is deterministic

The Trusted Account contribution collapses immediately when:
  • The user removes the linkage
  • BotShield detects a compromise signal from the linked platform
  • The user has no Face ID event for MULTIPASS_TTL_DAYS = 7 days (Path 1 freshness lapses; the takeover screen prompts re-verification before MultiPass returns to active)

​
Linkage Establishment

The linkage record itself is established inside an active, Face-ID-gated BotShield session: 
1. User opens BotShield
2. Face ID fires — Secure Enclave attestation
3. BotShield session established — user is verified present
4. User navigates to MultiPass tab → taps + Add
5. OAuth flow initiates (PayPal, LinkedIn, X, etc.)
6. User authorizes on the platform (password or passkey — platform's concern)
7. Platform issues token — BotShield stores linkage with class A or B classification
8. Linkage record written:
     botshield_user_id ↔ platform_account_id
     class             = 'A' | 'B'  (immutable from this point)
     linked_at         = Face ID event timestamp from step 2
     status            = 'active'
9. After 14 days the linkage is "mature" and contributes to the TTL boost

​
Identity Corroboration, Not Identity Verification

Trusted Accounts confirm that a verified human authorized this relationship. They do not attest that the human is present on those platforms. BotShield cannot and does not claim to verify human presence on PayPal or LinkedIn — only that a BotShield-verified human linked their account there. This distinction is maintained in all product copy, developer documentation, and platform conversations. The two jobs are:
  • Face ID + Secure Enclave — sole source of presence attestation
  • Trusted Account linkage — identity corroboration, contributes to MultiPass durability via the Class A/B boost math
  • Human Presence — what BotShield verifies, the verdict + reason contract, and the user-facing tier
  • Signal Durability — the streak mechanism that combines with Class A/B boosts to produce ttlHours