Trial Signup & Card Gate

New human signups on AINative Studio go through a card-gated 3-day free trial. A valid payment card must be attached through a Stripe Checkout session before the account is created. This applies to both email/password signups and OAuth signups (GitHub, Google, LinkedIn).

Who is gated

The card gate applies to interactive human signups. Keyless signup sources are exempt by design: Instant DB and agent signups (agents cannot enter a card), and the AINative Builder (which captures the card later, at the Live/upgrade step). The gate is also controlled server-side by the REQUIRE_TRIAL_CARD flag.

How the gate behaves

When a signup is subject to the gate and no verified checkout session is present, the register/callback request is rejected with HTTP 402 Payment Required and a structured body:

{
  "code": "TRIAL_CARD_REQUIRED",
  "error_code": "TRIAL_CARD_REQUIRED",
  "message": "A credit card and 3-day trial are required to sign up. Start your trial to continue.",
  "checkout_endpoint": "/api/v1/auth/create-trial-checkout",
  "email": "user@example.com"
}

The email is echoed back so an OAuth callback (which has no signup form) can open trial checkout for the right user. On receiving a 402 with error_code: TRIAL_CARD_REQUIRED, send the user to trial checkout.

Starting trial checkout

Create a Stripe Checkout session for the trial:

POST /api/v1/auth/create-trial-checkout
Content-Type: application/json

{
  "email": "user@example.com",
  "name": "Jane Developer",
  "plan": "Pro",
  "provider": "github"
}

Field	Required	Description
email	Yes	Email the account will be created under
name	No	Display name
plan	No	Selected plan (Pro, Business, Hobbyist; aliases resolve). Drives the Stripe price. Omit → Hobbyist
provider	No	github, google, or linkedin for OAuth signups, so the post-payment resume returns to the OAuth callback instead of the email finalizer

Response:

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_...",
  "session_id": "cs_test_...",
  "customer_id": "cus_..."
}

Redirect the user to checkout_url. A card is required up front; the trial cancels automatically if no card is attached (anti-farming).

Finishing signup

After the card is captured, Stripe returns to the finalizer with the checkout session id:

• Email signups: /signup?stripe_session_id={CHECKOUT_SESSION_ID} → the page calls POST /api/v1/auth/register with the stripe_session_id.
• OAuth signups: /login/callback?provider={provider}&stripe_session_id={CHECKOUT_SESSION_ID} → the callback re-runs the gate with the verified session.

The backend verifies the session with Stripe (it must exist, be complete, and match the signup email) before creating the account. A card already backing another active subscription, or a prepaid card, is rejected with a 402 (TRIAL_CARD_VELOCITY / TRIAL_CARD_REQUIRED).

Related endpoints

Endpoint	Method	Purpose
/api/v1/auth/create-trial-checkout	POST	Start the card-gated trial checkout session
/api/v1/auth/register	POST	Finalize an email signup (pass stripe_session_id)

See Authentication for JWT, API key, and OAuth details.