Vercel

FastYoke supports two paths to a working tenant:

• Direct signup — visit /signup, create an account, and get a Free-plan tenant immediately.
• Vercel Marketplace install — add FastYoke from the Vercel integration catalog; the install saga provisions the org, tenant, and API credentials automatically, then emails you an activation link.

Both paths converge on the same tenant shape: a FastYoke admin account, a scoped fy_pat_* API token, and four environment variables written into your linked Vercel project.

Marketplace install path

1. OAuth consent

When you install FastYoke from the Vercel integration catalog, Vercel redirects your browser to:

GET /vercel/oauth/authorize

This page displays a region selector (the FastYoke instance your data will be bound to). Submitting the form signs an OAuth state nonce and redirects to Vercel's approval URL.

2. Install saga

After you approve the Vercel consent screen, Vercel calls the registered callback:

GET /vercel/oauth/callback

The callback exchanges the authorization code for an access token, stores it encrypted, and starts a provisioning saga. The saga advances through these states in order:

pending
  → org_created
  → tenant_created
  → db_seeded
  → token_minted
  → env_injected         ← env vars written to your Vercel project
  → webhooks_registered  ← lifecycle webhooks registered
  → complete             ← API key is live
  → user_invited         ← activation email sent (terminal happy-path state)

During provisioning an interstitial page polls GET /vercel/oauth/status?saga=<id> for progress. If the saga stalls or errors it transitions to failed; the LIFO rollback removes every artifact created so far (token → tenant → org) and leaves the platform clean for a retry.

3. Env-var injection

When the saga reaches env_injected, four environment variables are written across production, preview, and development environments on your linked Vercel project:

FASTYOKE_API_KEY and FASTYOKE_WEBHOOK_SECRET are stored as Vercel encrypted variables — readable by your deployments at runtime but not visible in the Vercel dashboard UI. The other two are plain (visible in the dashboard).

Injection is idempotent: the saga lists existing env-var keys first and skips any that are already present, so retries and project-rename re-injections never create duplicates.

4. Activation email

After complete, the saga calls GET https://api.vercel.com/v2/user to retrieve the installing user's email, then sends a welcome email containing a one-time activation link:

https://app.fastyoke.com/vercel-claim/<token>

The claim token is valid for 7 days. Clicking the link:

• New FastYoke account — presents a password-set form. On submit, your account is activated, a JWT is issued, and you land at /admin.
• Existing FastYoke account — shows a login prompt. Signing in silently attaches the new Vercel tenant to your existing account; no separate claim step required.

Direct signup path

Visit /signup to create a FastYoke account without going through the Vercel Marketplace. You receive a Free-plan tenant immediately and can start building. To link a Vercel project later, add the four env vars from the table above manually using fy_pat_* tokens you generate at /admin/settings.

After activation

Once your account is active, the admin shell is at /admin. Key surfaces for Vercel-connected tenants:

• /admin/settings — tenant settings, branding, plan tier.
• /admin/settings (API Tokens tab) — manage fy_pat_* tokens.
• /admin/integrations — outbound webhook credentials (Twilio, SendGrid, generic REST).

Lifecycle events

FastYoke registers lifecycle webhooks with Vercel during the webhooks_registered saga step. The following events are handled automatically:

Token rotation

Platform operators can rotate the FASTYOKE_API_KEY written into your Vercel project without downtime:

POST /vercel/installations/<installation_id>/rotate
{ "reason": "<audit note>" }

The rotation:

1. Mints a fresh fy_pat_* token.
2. Pushes it to Vercel as the new FASTYOKE_API_KEY env var.
3. Revokes the prior token.

If step 2 (the Vercel push) fails, step 1 is rolled back so the old token stays live — your project never has a broken API key. Rotation is platform-admin gated; it cannot be triggered from the tenant dashboard.

Operator reference

Environment variables (server-side)

The Vercel integration is disabled by default. Set all three to enable /vercel/* routes:

All three must be set; any missing value disables every /vercel/* route (returns 503).

Saga reconciliation CLI

If a saga stalls or the activation email needs to be resent, use the fastyoke-admin binary:

# Inspect a saga (read-only, safe on any id)
fastyoke-admin vercel-saga-reconcile \
  --id <saga-id> \
  --action dry

# Drive a db_seeded saga to token_minted
fastyoke-admin vercel-saga-reconcile \
  --id <saga-id> \
  --action complete

# Resend the activation email (requires --confirm matching --id)
fastyoke-admin vercel-saga-reconcile \
  --id <saga-id> \
  --action user-invite \
  --confirm <saga-id>

# LIFO rollback — removes all artifacts (requires --confirm)
fastyoke-admin vercel-saga-reconcile \
  --id <saga-id> \
  --action force-rollback \
  --confirm <saga-id>

dry is the safe default and requires no TENANT_DATA_DIR. force-rollback requires TENANT_DATA_DIR to be set (same as the running app) so it can remove the per-tenant SQLite file.

The saga sweeper worker automatically flips stale pending sagas to failed every 30 seconds, keeping the platform clean without manual intervention.