# Foil

- [Start building with Foil](https://usefoil.com/docs/index.md): Detect AI agents, headless browsers, and automation with Foil. Verify sealed sessions on your backend.
- [Quickstart](https://usefoil.com/docs/quickstart.md): Add Foil bot detection in 5 minutes. Load the browser client, request a sealed session handoff, verify it on your backend, and apply policy by verdict.
- [How it works](https://usefoil.com/docs/how-it-works.md): See how Foil detects AI-controlled browsers and automation: 350+ signals across seven scoring categories, server-side scoring, and backend verification of sealed tokens.
- [Browser SDK](https://usefoil.com/docs/browser-sdk.md): Integrate the Foil browser SDK: import t.js, call start() with your publishable key, and get a sealed session handoff with getSession() at action time.
- [Android SDK](https://usefoil.com/docs/android-sdk.md): Add the Foil Android SDK to your Kotlin app from Maven Central, configure it in Application.onCreate(), and hand sealed sessions to your backend to verify.
- [iOS SDK](https://usefoil.com/docs/ios-sdk.md): Add the Foil iOS SDK to your Swift app with Swift Package Manager, configure it at launch, and hand sealed sessions to your backend for verification.
- [Server verification](https://usefoil.com/docs/server-verification.md): Verify Foil sealed tokens on your backend with a local check, no network call, then read the verdict and risk score to allow, challenge, or block actions.
- [Webhooks](https://usefoil.com/docs/webhooks.md): Receive signed webhook events from Foil when sessions change state, verify HMAC signatures, and handle retries idempotently.
- [Testing your integration](https://usefoil.com/docs/testing.md): Test your Foil integration with test keys and simulated bot traffic from Playwright, Puppeteer, or Selenium, then confirm verdicts and enforcement paths.
- [Going to production](https://usefoil.com/docs/going-to-production.md): Take Foil to production safely: start in report-only mode, monitor verdicts, add soft challenges, then enable hard enforcement once signals look stable.
- [Signup & account creation](https://usefoil.com/docs/use-cases/signup.md): Stop fake signups and automated account creation. Verify Foil sealed tokens at registration and block bots and AI agents before you create the account.
- [KYC fraud reduction](https://usefoil.com/docs/use-cases/kyc.md): Reduce KYC fraud before your vendor runs. Use Foil to catch synthetic identities, identity farming, and anti-detect browsers at the verification step.
- [Login & credential stuffing](https://usefoil.com/docs/use-cases/login.md): Block account takeover at login. Use Foil to detect credential stuffing, step up inconclusive sessions, and rate-limit by visitor fingerprint, not just IP.
- [Checkout & payment](https://usefoil.com/docs/use-cases/checkout.md): Use Foil at checkout to decline automated payments, give your fraud review device and network context, and keep session records for chargeback disputes.
- [User-generated content](https://usefoil.com/docs/use-cases/user-generated-content.md): Stop LLM spam and automated posting on user-generated content. Block AI-agent submissions at the composer and cap posting velocity per visitor fingerprint.
- [API abuse & scraping](https://usefoil.com/docs/use-cases/api-abuse.md): Stop API abuse and LLM scraping while allowing legitimate crawlers. Verify Foil sessions across API calls and split policy by attribution.
- [Promo & trial abuse](https://usefoil.com/docs/use-cases/promo-abuse.md): Stop promo abuse and free-trial farming. Use Foil's visitor fingerprint to catch repeat claims across account rotations, cookie clears, and incognito.
- [Verdicts & scoring](https://usefoil.com/docs/verdicts-and-scoring.md): Understand Foil verdicts and risk scores, how human, bot, and inconclusive relate to typical score ranges, and how to apply them in your backend policy.
- [Detection categories](https://usefoil.com/docs/detection-categories.md): Learn how Foil scores sessions across environment, fingerprint, behavioral, timing, and anti-tamper detection categories to produce a verdict.
- [Browser compatibility](https://usefoil.com/docs/browser-compatibility.md): Check Foil browser compatibility: supported Chrome, Edge, Firefox, and Safari versions, required APIs, and rollout guidance for webviews and embedded shells.
- [Frontend JavaScript compatibility](https://usefoil.com/docs/runtime-instrumentation.md): Learn how frontend monitoring, analytics, session replay, and tag manager scripts affect Foil runtime signals, and validate your stack before enforcing.
- [Content Security Policy](https://usefoil.com/docs/content-security-policy.md): Configure Content Security Policy directives for the Foil browser SDK, including the script-src, connect-src, worker-src, and frame-src values you need.
- [Security and privacy](https://usefoil.com/docs/privacy-and-data.md): Review what data Foil collects and never collects, how Foil encrypts data in transit and at rest, and the privacy disclosures your deployment needs.
- [Troubleshooting](https://usefoil.com/docs/resources/troubleshooting.md): Troubleshoot common Foil integration issues: getSession() rejections, sealed token failures, inconclusive verdicts, and webhook 401s, plus FAQs.
- [API introduction](https://usefoil.com/docs/api-reference/introduction.md): Explore the Foil API: base URLs, the v1 REST surface for sessions, fingerprints, agents, organizations, and webhooks, plus conventions shared by every endpoint.
- [Authentication](https://usefoil.com/docs/api-reference/authentication.md): Authenticate Foil API requests with publishable and secret keys, including Bearer token usage, key scopes, environments, rotation, and revocation.
- [Errors](https://usefoil.com/docs/api-reference/errors.md): Handle Foil API errors with the structured JSON envelope, stable error codes, HTTP status codes, retry semantics, and request IDs for support.
- [Pagination](https://usefoil.com/docs/api-reference/pagination.md): Paginate Foil API list endpoints with cursor-based pagination, including limit and cursor parameters, filters, and SDK auto-pagination helpers.
- [Rate limits](https://usefoil.com/docs/api-reference/rate-limits.md): Understand Foil API rate limits per organization and key type, read X-RateLimit response headers, handle 429 errors, and retry with Retry-After.
- [Versioning](https://usefoil.com/docs/api-reference/versioning.md): Learn how Foil API versioning works under /v1/, which changes are additive versus breaking, and how deprecations, sunsets, and SDK releases ship.
- [Collect API](https://usefoil.com/docs/api-reference/transport.md): Review the Collect API endpoints the Foil browser SDK uses to open transport sessions, stream encrypted observation batches, and mint sealed handoffs.
- [Sessions API](https://usefoil.com/docs/api-reference/sessions.md): Retrieve and list scored Foil sessions with a secret key, including the verdict, risk score, decision detail, and signals, plus your own user ID linkage.
- [List sessions](https://usefoil.com/docs/api-reference/sessions/list-sessions.md): Requires the `sessions:list` secret-key scope.
- [Break down sessions](https://usefoil.com/docs/api-reference/sessions/break-down-sessions.md): Counts the sessions that match the filters, grouped by one dimension, with each group's bot, human and inconclusive counts. Counts lag new scores by up to five minutes. Requires the `sessions:list` secret-key scope.
- [Retrieve one session](https://usefoil.com/docs/api-reference/sessions/retrieve-one-session.md): Requires the `sessions:read` secret-key scope.
- [Update a session](https://usefoil.com/docs/api-reference/sessions/update-a-session.md): Set or clear the customer-supplied `client_user_id` for a session. Requires the `sessions:update` secret-key scope.
- [Visitor fingerprints API](https://usefoil.com/docs/api-reference/fingerprints.md): List and retrieve visitor fingerprints with the Foil API, including lifecycle data, anchors, and recent linked sessions for correlation.
- [List visitor fingerprints](https://usefoil.com/docs/api-reference/visitor-fingerprints/list-visitor-fingerprints.md): Requires the `fingerprints:list` secret-key scope.
- [Retrieve one visitor fingerprint](https://usefoil.com/docs/api-reference/visitor-fingerprints/retrieve-one-visitor-fingerprint.md): Requires the `fingerprints:read` secret-key scope.
- [Agent IP rotation API](https://usefoil.com/docs/api-reference/agents.md): Check whether an agent should rotate its current proxy IP address.
- [Check whether an agent should rotate its IP](https://usefoil.com/docs/api-reference/agents/check-whether-an-agent-should-rotate-its-ip.md): Requires the database-controlled organization entitlement and the `agents:ip_rotation` secret-key scope. Each submitted IP consumes one secret-key rate-limit unit, so a 10-item batch costs 10 units. The response reports that cost in `X-RateLimit-Cost`.
- [List webhook endpoints](https://usefoil.com/docs/api-reference/webhooks/list-webhook-endpoints.md): Requires Authorization: Bearer sk_* with the webhooks:read scope.
- [Create a webhook endpoint](https://usefoil.com/docs/api-reference/webhooks/create-a-webhook-endpoint.md): Requires Authorization: Bearer sk_* with the webhooks:manage scope. The signing_secret is returned only in this response and rotation responses.
- [Update a webhook endpoint](https://usefoil.com/docs/api-reference/webhooks/update-a-webhook-endpoint.md): Requires Authorization: Bearer sk_* with the webhooks:manage scope. Updating event_types replaces the endpoint subscriptions.
- [Disable a webhook endpoint](https://usefoil.com/docs/api-reference/webhooks/disable-a-webhook-endpoint.md): Requires Authorization: Bearer sk_* with the webhooks:manage scope.
- [Rotate a webhook signing secret](https://usefoil.com/docs/api-reference/webhooks/rotate-a-webhook-signing-secret.md): Requires Authorization: Bearer sk_* with the webhooks:manage scope. The new signing_secret is returned only in this response.
- [Send a test webhook](https://usefoil.com/docs/api-reference/webhooks/send-a-test-webhook.md): Requires Authorization: Bearer sk_* with the webhooks:manage scope. Enqueues a webhook.test delivery for the selected endpoint.
- [List events](https://usefoil.com/docs/api-reference/events/list-events.md): List organization events. Requires Authorization: Bearer sk_* with the webhooks:read scope.
- [Retrieve an event](https://usefoil.com/docs/api-reference/events/retrieve-an-event.md): Retrieve one organization event and its webhook delivery attempts. Requires Authorization: Bearer sk_* with the webhooks:read scope.
- [Organizations API](https://usefoil.com/docs/api-reference/organizations.md): Manage Foil organizations and API keys over REST: create organizations, provision publishable and secret keys, set scopes, and rotate or revoke keys.
- [Create an organization](https://usefoil.com/docs/api-reference/organizations/create-an-organization.md): Requires the `organizations:create` secret-key scope.
- [Retrieve one organization](https://usefoil.com/docs/api-reference/organizations/retrieve-one-organization.md): Requires the `organizations:read` secret-key scope.
- [Update a organization](https://usefoil.com/docs/api-reference/organizations/update-a-organization.md): Requires the `organizations:update` secret-key scope.
- [List organization API keys](https://usefoil.com/docs/api-reference/api-keys/list-organization-api-keys.md): Requires the `api_keys:read` secret-key scope.
- [Create an organization API key](https://usefoil.com/docs/api-reference/api-keys/create-an-organization-api-key.md): Requires the `api_keys:manage` secret-key scope.
- [Update an organization API key](https://usefoil.com/docs/api-reference/api-keys/update-an-organization-api-key.md): Requires the `api_keys:manage` secret-key scope.
- [Revoke a organization API key](https://usefoil.com/docs/api-reference/api-keys/revoke-a-organization-api-key.md): Requires the `api_keys:manage` secret-key scope.
- [Rotate a organization API key](https://usefoil.com/docs/api-reference/api-keys/rotate-a-organization-api-key.md): Requires the `api_keys:manage` secret-key scope.

## OpenAPI Specs

- [openapi](/docs/api-reference/openapi.json)


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