Story

Customer journey

Meet Alex, founder of Acme AI — an image generator. Alex wants Free users to get 1,000 credits / month and Pro users 50,000, plus PDF export on Pro only. Here is how Alex uses UsageGate end to end.

1. Create a workspace

Alex opens /signup, enters company name Acme AI, continues with Google, and lands in the dashboard. One Google login can own several companies later.

2. Draw access rules

On Access rules, Alex builds:

Feature keys (ai_credits, export_pdf) are what the SDK will ask about. Details: Define access rules.

3. Create an API key

Dashboard → API keys → Generate. Alex copies the key once into Acme's backend env as USAGEGATE_KEY.

4. Gate the product

When Maya clicks “Generate image” in Acme:

import { GateClient } from "@usagegate0/sdk";

const gate = new GateClient(process.env.USAGEGATE_KEY!, {
  baseUrl: process.env.USAGEGATE_API_BASE_URL,
});

export async function generate(mayaId: string) {
  if (!(await gate.canAccess(mayaId, "ai_credits"))) {
    return { error: "Upgrade to continue" }; // 402 in your API
  }
  await gate.consume(mayaId, "ai_credits", 1);
  return runModel();
}

Maya never sees UsageGate. Acme still owns login. UsageGate only answers allow / deny and burns credits atomically.

5. Connect Stripe (required)

Acme already sells Pro in their Stripe — that account also owns the billing period. Alex:

1. Points Stripe webhooks to POST {your-usagegate-host}/api/webhooks/stripe
2. Pastes the signing secret (whsec_…) on Stripe in UsageGate
3. Puts grant metadata on the Pro subscription (see Connect Stripe)

When Maya upgrades, Stripe fires invoice.paid → UsageGate verifies the signature → sets Maya's ai_credits to 50,000 and resetAt to the subscription's current_period_end → next generate works until that period ends. Next invoice refills again. Details: billing periods.

6. Watch and adjust

Overview shows checks, burns, and denials. End users lists Maya's balances. Alex can grant a trial with gate.grant() without waiting for Stripe.

What Alex did not build

• No custom credit ledger or Redis race logic
• No webhook idempotency tables
• No “did this invoice already refill?” bugs

Next: Quickstart or the AI setup prompt.