# Security model

Canonical URL: https://docs.viralspy.com/docs/security



## Boundaries [#boundaries]

* API keys are high-entropy one-time secrets stored as versioned HMAC digests.
* Each key is bound to a user membership and one explicit organisation.
* OAuth access tokens must be asymmetrically signed, short-lived, issued by the configured Supabase issuer, and audience-bound to `https://api.viralspy.com/mcp`.
* A custom access-token hook gives MCP tokens a restricted `viralspy_mcp` database role and a distinct token-type claim. The API rechecks the stored OAuth grant and membership.
* The MCP server never passes the client's bearer token to Typesense, Supabase data APIs, or the web analyst. Internal service calls use separate credentials and a timestamped HMAC bridge.

## Request protection [#request-protection]

The edge enforces failed-authentication, burst, per-credential, and per-organisation limits before expensive work. Supabase provides an authoritative cross-isolate fair-use ledger. Signed cursors bind pagination to a query and expire after 24 hours.

Analyst calls require idempotency, claim concurrency before work begins, record terminal status, and stream heartbeats. Identical in-flight work returns status rather than running twice.

## Client responsibilities [#client-responsibilities]

* Keep secrets on trusted servers or in environment-backed client stores.
* Grant `agent:request` only to workloads that need it.
* Rotate keys on staff or system changes and revoke unused credentials.
* Validate responses before using fields in automated decisions.
* Treat TikTok and ViralSpy-derived intelligence according to applicable platform terms and law.

For a suspected credential leak, revoke or rotate the key in [API settings](https://app.viralspy.com/settings/api) immediately, then contact support with request IDs—never the secret itself.