Visitor Auth and Access

Use this guide to understand how visitors authenticate and manage access entitlements.

When to use

You are a creator setting up protected pages/files and need to understand the visitor experience.
You are debugging a visitor who cannot access content.
You are integrating the checkout flow into a custom frontend.

How visitor auth works

Visitors authenticate using passwordless magic links. There are no passwords or usernames.

Visitor submits their email.
A magic link is sent to that email (valid for 15 minutes).
Clicking the link sets a session cookie (_10x_visitor, valid for 30 days).
The cookie grants access to visitor access endpoints and entitlement checks.

Page access modes

Mode	Visitor requirement
PUBLIC	None — anyone can view
FREE_WITH_LOGIN	Visitor must authenticate (no payment)
PAID	Visitor must have an active purchase

UI path (buyer perspective)

Visitor opens a paid page at https://{handle}.{PUBLIC_DOMAIN}/{pageSlug}.
If payment is required, the visitor enters their email.
They click the magic link in their email.
After authentication, they are redirected to Stripe checkout.
On successful payment, they are redirected back and can access the page.

UI path (creator perspective)

Open https://app.{PUBLIC_DOMAIN}.
Navigate to your handle and open the Pages section.
Create or edit a page and set the access mode to PAID.
Set the price and currency.
Ensure your Stripe Connect account is connected (see Revenue settings).

Required auth

No auth for magic link request and access checks.
Visitor session cookie for checkout, access list, and group buy interest.
Creator-level JWT for issuing refunds.

API fallback

Visitor authentication

POST /v2/visitor/auth/magic-link — request a magic link.

{
  "email": "buyer@example.com"
}

POST /v2/visitor/auth/verify — verify the token from the magic link. Sets the session cookie.
GET /v2/visitor/me — get the authenticated visitor profile.
POST /v2/visitor/auth/logout — clear the session.

Access check

POST /v2/public/pages/{handle}/{pageSlug}/access-check

Returns hasAccess (boolean) and reason (public, visitor_auth_required, entitled, purchase_required).

Checkout

POST /v2/public/pages/{handle}/{pageSlug}/checkout

Requires a visitor session cookie. Returns a Stripe checkout URL. Redirect the visitor to that URL.

{
  "successUrl": "https://example.com/thanks",
  "cancelUrl": "https://example.com/cancelled"
}

View access

GET /v2/visitor/access

Returns the visitor's access history across paid pages, free-login pages, and allowlisted files with resource type, access type, and status.

Refund (creator only)

POST /v2/handles/{handle}/pages/{pageSlug}/refund

{
  "visitorId": "vis_abc123"
}

Initiates a Stripe refund and revokes the visitor's access.

Group buys

Group buys let visitors express interest in a collective purchase. When the target quantity is reached, the creator can activate the offer.

GET /v2/public/group-buys/{handle}/{groupBuySlug} — view group buy details (public).
POST /v2/public/group-buys/{handle}/{groupBuySlug}/interest — express interest (visitor session required).
GET /v2/public/group-buys/{handle}/{groupBuySlug}/my-interest — check own interest status.
DELETE /v2/public/group-buys/{handle}/{groupBuySlug}/my-interest — withdraw interest.

Common errors

Code	Error	Cause
401	`visitor_unauthorized`	Missing or invalid visitor session
401	`expired_magic_link`	Magic link older than 15 minutes
401	`used_magic_link`	Magic link already consumed
404	`page_not_found`	Page does not exist or is not published
409	`page_not_paid`	Checkout attempted on a non-paid page
409	`connect_not_configured`	Creator has not connected Stripe
409	`already_refunded`	Purchase was already refunded

Entitlement logic

A visitor has access to a paid page when:

A purchase record exists for that visitor and page.
The grant type is not REFUNDED.
The access has not been revoked.

If a refund is issued (by the creator or via Stripe), the entitlement is revoked and the visitor loses access.