Sub-Account API

Mint a key per customer.
In one API call.

Multi-tenant AI billing without writing your own billing layer. Scoped keys with spend caps, rate limits, isolated analytics, and OpenAI-compatible drop-in. Cost + 5%, no extra fee for sub-accounts.

Get your key Read the API docs
Spend caps enforced at edge Per-customer analytics Works with every OpenAI-SDK
60-second integration

One POST. Hand the key to your customer.

The sub-account key is a normal sk-aig-* key. It works in every framework that supports the OpenAI SDK — no SDK changes, no special routing on your side.

create_sub_account.ts
your backend
// On every new customer signup in your app:
const r = await fetch("https://api.aigateway.sh/v1/sub-accounts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${AIGATEWAY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: `customer_${customerId}`,
    spend_cap_cents: 5000,         // $50/mo hard cap
    rate_limit_rpm: 300,
    allowed_models: ["openai/gpt-5.4-mini",
                     "anthropic/claude-haiku-4.5"],
    default_tag: `tenant:${customerId}`,
  }),
});
const { key, id } = await r.json();
// → key: "sk-aig-..."   id: "sa_9f3k..."
// Save id; hand key to customer (or proxy through your backend).
customer_app.py
their app
# Your customer uses it like any other OpenAI key:
from openai import OpenAI

client = OpenAI(
    base_url="https://api.aigateway.sh/v1",
    api_key="sk-aig-...",  # the sub-account key
)

r = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[{"role": "user",
               "content": "Hi"}],
)

# Spend lands on YOUR AIgateway bill, tagged tenant:abc
# Hits cap at $50 → returns 402 payment_required
# Webhook sub_account.budget.exhausted fires to your backend
Primitives

Six things you'd otherwise build yourself.

Sub-accounts are the billing layer most multi-tenant AI products end up building from scratch on top of a single-provider key. We've already built it.

Spend caps
Hard limits, atomic at the edge.
Set a dollar cap per sub-account per month. Once hit, requests return 402 with a structured error — no overage, no surprise bill. Cap is enforced at the edge before the request leaves us.
Rate limits
Different limits per customer tier.
Per-sub-account RPM, RPD, and TPM. Give your free-tier users 60 RPM and your enterprise customers 10,000 — same code, one config line.
Cost attribution
Know exactly what each customer spent.
Every request from a sub-account carries its ID into the usage log. Query by sub_account_id, by tag, by model, by day — for rebilling, margin analysis, or just to know which customer just discovered Opus 4.7.
Model scoping
Different catalogs for different tiers.
Allow-list specific models per sub-account. Free tier gets Llama 4 + Gemini Flash; Pro gets everything; Enterprise gets BYOK routing too.
Webhooks
Real-time events for your billing system.
Subscribe to sub_account.created, .budget.warning (80%), .budget.exhausted (100%), .rate_limited, .request.failed. Wire them straight into your CRM, Stripe, or Slack.
BYOK passthrough
Your provider contracts, our billing layer.
Attach Anthropic / OpenAI / Google keys at the parent level. Sub-accounts route through them automatically; 5% platform fee is waived on those calls. Volume discounts stay with you.
Use cases

Built for products with end users.

If your product has customers — and your customers' spend should NOT show up on your founder credit card — sub-accounts are how you do it without writing your own billing layer.

AGENT MARKETPLACE
Per-developer keys for your agent platform
Hand every dev who joins your marketplace a scoped key. They build agents on your platform; spend lands on your bill; you re-bill them programmatically (or include it in their plan).
Composio · Replit Agents · v0 · Mastra Cloud
VERTICAL SAAS
Free + Pro tiers with isolated AI budgets
Your free-tier users get a $5/month AI budget on cheap models. Pro users get $100 across the full catalog. Enterprise users BYOK. One library call per signup — billing happens at the edge.
Workflow apps · Legal AI · Healthcare CRMs
CHAT PRODUCT
Pay-per-conversation chat with cost guards
Spin up a sub-account per conversation thread with a $0.50 cap. Out of budget = end the chat. No more 'a single user discovered context stuffing and burned $400'.
Character.ai-style apps · Roleplay platforms
Works with

Drop into your existing auth + billing.

Pair sub-accounts with your identity, billing, and CRM stack. Mint on user creation. Cap based on plan. Surface in your existing dashboards.

Pricing

No fee per sub-account.

Sub-accounts are included in standard PAYG. You pay model cost + 5% on the actual usage, whether it lands on the parent key or a sub-account. No per-seat fee. No per-sub-account fee. No charge if a sub-account never gets used.

See full pricingStart with $5 free*

* Free credit applies only to selected models. Expires 7 days after signup. See the list.

FAQ

Sub-account questions, answered.

What is the Sub-Account API?
One AIgateway API call mints a scoped API key for each of your customers. Each key has its own spend cap, rate limit, default cost-attribution tag, and isolated usage analytics. You hand the key to your customer (or hold it for them); when they make calls, the spend lands on your AIgateway account with a tag that points back to that sub-account.
How is this different from just creating multiple AIgateway keys?
API keys are user-scoped (one user, many keys, shared wallet). Sub-accounts are customer-scoped (one parent user, many sub-accounts, each with its own wallet limit + analytics). You can mint and rotate them programmatically — no clicking through a dashboard for every new customer.
Does this work with the OpenAI SDK?
Yes. A sub-account key is a normal sk-aig-* key — it works with the OpenAI SDK, Vercel AI SDK, LangChain, LlamaIndex, Cline, Cursor, every framework. Your customer drops it in wherever they'd drop an OpenAI key.
How does billing work?
You pay AIgateway model cost + 5% (the standard PAYG rate). What you charge your customer is up to you — usage-based, flat, included in your plan, whatever. We surface their spend grouped by sub_account_id so you can rebill or just monitor margin.
Can sub-accounts use different models or get different rate limits?
Yes. You can scope a sub-account to specific models, set per-sub-account rate limits in req/min, and enforce monthly spend caps that hard-stop at 100%.
What happens if a sub-account hits its spend cap?
Requests return HTTP 402 (payment_required) with a structured error. You can listen on the sub_account.budget.exhausted webhook to surface the cap to your end user, raise it programmatically, or rotate the key.
Do you support BYOK on sub-accounts?
Yes. Attach your provider keys at the parent level; sub-accounts route through your keys when available. You waive the 5% platform fee on BYOK traffic.
Is there extra cost for sub-accounts?
No. Sub-accounts are included in PAYG. You only pay model cost + 5% on whatever your customers actually use. No per-seat, no per-sub-account fee.