Quickstart

You need a customer token (sk_) from the console. Everything below is one end user, one key, one call, the smallest thing that produces a real number on a real page.

The whole thing, in commands

Every step below, with no language to choose. seams is the CLI (npm i -g @ourseams/cli); everything it does is also an HTTP call, and the same run in curl is on the second tab.

export SEAMS_API_KEY="sk_acme_…"

seams models add acme/smart --source anthropic/claude-sonnet-4
seams bundles add pro --name Pro
seams bundles allow pro acme/smart

# mint a key for one end user; the secret is in this response and nowhere else
seams keys mint --user alice --bundle pro --cap 50 --expires 1h

# your application's own hostnames, as full urls
seams apps show acme

# call the gateway with the end user's ak_
curl https://acme.gw.ourseams.com/v1/chat/completions \
  -H "Authorization: Bearer $END_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "acme/smart", "messages": [{ "role": "user", "content": "Say hello" }] }'

# what it cost
seams usage --user alice

curl -X POST https://api.ourseams.com/v1/keys \
  -H "Authorization: Bearer $SEAMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "alice",
    "email": "[email protected]",
    "bundle": "pro",
    "capMicros": "50000000",
    "expiresAt": "2099-01-01T00:00:00Z"
  }'

# { "id": "key_…", "key": "ak_acme_…", "keyPrefix": "ak_acme_a1b2c3",
#   "endUserId": "alice", "capMicros": "50000000", "expiresAt": "2099-01-01T00:00:00Z" }

Step by step

1. 1

   Store your customer token

   The sk_ token authenticates your backend to the Seams API. It mints end-user keys and reads usage. It is not the key your users hold.

   cli

   export SEAMS_API_KEY="sk_acme_…"

   Never ship an sk_ to a browser or a mobile app. It can mint keys and read every customer's spend.

2. 2

   Name a model and allow it on a bundle

   Create your alias, then allow it on the bundle you will mint under. Skip bundles add if onboarding already created pro.

   clitypescriptpython

   seams models add acme/smart --source anthropic/claude-sonnet-4
   seams bundles add pro --name Pro
   seams bundles allow pro acme/smart

   A router is optional. After its targets are on a bundle, seams routers add attaches it. See Routers.

3. 3

   Mint a key for one end user

   Mint under your own identifier. If that person does not exist yet, mint creates them and opens their balance.

   clitypescriptpython

   curl https://api.ourseams.com/v1/keys \
     -H "Authorization: Bearer $SEAMS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "endUserId": "alice", "email": "[email protected]", "bundle": "pro", "capMicros": "50000000" }'

   The secret is never retrievable again. Save it before you do anything else.

4. 4

   Point the client at your gateway

   Your application has its own gateway host. It speaks the OpenAI, Anthropic, and Gemini wire formats, so the client you already use works unchanged. Point that host as the base URL, and pass the end user's ak_ instead of your provider key.

   openaianthropicgeminicurl

   import OpenAI from "openai"
   
   const client = new OpenAI({
     baseURL: "https://<app>.gw.ourseams.com/v1",
     apiKey: endUserKey,
   })
   
   const res = await client.chat.completions.create({
     model: "acme/smart",
     messages: [{ role: "user", content: "Say hello" }],
   })

5. 5

   Read what it cost

   Usage is queryable immediately, and the same number is on the customer's portal page.

   clitypescriptpython

   curl "https://api.ourseams.com/v1/usage?endUserId=alice" \
     -H "Authorization: Bearer $SEAMS_API_KEY"

What you just built

• An alias on a bundle, and a key that may call it
• A metered call with a usage row and portal spend under your brand

Where to go next