Skip to main content

​
Trusted Account Signal

BotShield’s verification endpoint supports two distinct signal paths. The path that fires depends on what the querying platform knows about the user — and both produce an authoritative valid response backed by the same underlying verification event.

​
The Two Paths

Path 1 — Anonymous Verified Human Presence

Hardware-backed HPS event within a TTL window. This is the V2 default. A Face ID / Touch ID event on a registered device attests presence. The signal decays over time per the Signal Durability multiplier.

Path 2 — Verified Name Presence Attestation

Trusted Account match produces a standing valid signal. If the querying platform is itself a Trusted Account linked to this user, the match IS the signal — no TTL evaluation. The user authorized this relationship inside an active Face-ID-gated BotShield session. The relationship is the proof.

​
Why Two Paths

The two paths answer different questions about the same human:
PathIdentitySignal sourceTTLDecayStrength
Path 1AnonymousHardware HPS (Face ID / Secure Enclave)Yes — signal windowYes, weakens without activityTime-bound
Path 2Identity-linked via Trusted AccountTrusted Account linkage matchNone — standing booleanOnly collapses on linkage removal or 90-day absenceIdentity-bound, does not decay

​
How Path 2 Fires

When a platform calls signal/check with a querying_platform value, BotShield evaluates:
1

Is the querying platform a Trusted Account for this user?

BotShield looks up the user’s verified_accounts for an active row matching the querying_platform string (e.g. paypal, linkedin, x).
2

Is the user still within the 90-day BotShield activity window?

If the user has been auto-signed-out due to 90+ days of inactivity, Path 2 collapses along with Path 1. No valid BotShield account, no signal.
3

Both checks pass → Path 2 match

Return { valid: true, path: "trusted_account", signal_strength: "..." }. No TTL evaluation. The linkage is the signal.
4

Either check fails → fall through to Path 1

Standard TTL + multiplier evaluation. Return { valid, path: "hps" | null, signal_strength: "..." }.

​
Example Requests

Anonymous (Path 1 only): 
curl -X POST https://api.botshield.ai/operations/signal/check \
  -H "Authorization: Bearer <clerk_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "botshield_user_id": "728bc0c7-fb96-4ac9-b0e7-fa560374a079"
  }'

{
  "data": {
    "valid": true,
    "path": "hps",
    "signal_strength": "growing"
  }
}
Platform-aware (Path 2 attempt): 
curl -X POST https://api.botshield.ai/operations/signal/check \
  -H "Authorization: Bearer <clerk_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "botshield_user_id": "728bc0c7-fb96-4ac9-b0e7-fa560374a079",
    "querying_platform": "paypal"
  }'

{
  "data": {
    "valid": true,
    "path": "trusted_account",
    "signal_strength": "strong"
  }
}
When the user has linked PayPal as a Trusted Account, the response includes path: "trusted_account". If the same user has not linked PayPal, the response falls through to Path 1 and returns path: "hps" (or null when invalid).

​
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 ongoing boolean from account match is attesting to that moment — not to continuous presence, but to a verified human deliberately authorizing this relationship. That is a sound security guarantee.

​
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 — PayPal supports them, LinkedIn is rolling them out — 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 Path 2 signal collapses immediately and deterministically when:
  • The user removes the Trusted Account linkage
  • BotShield detects a compromise signal from the linked platform
  • The user has no BotShield activity for 90 days (auto sign-out fires, nulling all timestamps)
There is no grace window on Path 2. Valid flips to not valid the moment the condition is met.

​
Path 2 Linkage Establishment

The Trusted Account 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 My Presence → 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
8. Linkage record written:
     botshield_user_id ↔ platform_account_id
     timestamp = Face ID event from step 2
     status = active

​
What Platforms Should Do With path

The path field tells the querying platform how the signal was produced, not just whether it is valid. Platforms that want to apply stricter rules to anonymous signals can branch on it: 
const result = await botshield.signal.check({
  botshield_user_id,
  querying_platform: 'paypal',
});

if (result.path === 'trusted_account') {
  // User is identity-linked to this platform. Highest trust.
  // Pre-approved for most actions without additional friction.
  return allow();
}

if (result.path === 'hps' && result.valid) {
  // Anonymous hardware-backed presence. Still human, still recent.
  // Apply platform-specific scope rules.
  if (action === 'purchase' && result.signal_strength === 'newborn') {
    return challenge();
  }
  return allow();
}

// path === null or valid === false
return deny();

​
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, produces a standing verified signal for the querying platform