Core concepts

Keys and end users

One key per end user, and why never a header.

Attribution lives on the credential, not in the request. A key is minted for one end user and bound to their balance at that moment, so the caller never asserts who they are.

Why not a header

A header is an assertion. Anything holding the key could set it to anything, and your usage records would be a record of what callers claimed rather than what happened.

Create an end user and mint a key

seams users create ada --email ada@firm.com --bundle pro
seams keys mint --user ada --bundle pro --cap 5.00 --label "Ada laptop"

# ak_acme_m8avt…SIrY
# warning  shown once; store it now

import { Seams } from "@ourseams/sdk"

const seams = new Seams({ apiKey: process.env.SEAMS_API_KEY! })

await seams.users.create("ada", { email: "ada@firm.com", bundle: "pro" })
const key = await seams.keys.mint({
  endUserId: "ada",
  bundle: "pro",
  capMicros: "5000000",
  name: "Ada laptop",
})
// key.key is shown once

import os
from seams import Seams

seams = Seams(api_key=os.environ["SEAMS_API_KEY"])

seams.users.create("ada", email="ada@firm.com", bundle="pro")
key = seams.keys.mint(
    end_user_id="ada",
    bundle="pro",
    cap_micros="5000000",
    name="Ada laptop",
)
# key.key is shown once

Read and change the ceiling

seams keys show key_01J8Q…0x2m
seams keys cap key_01J8Q…0x2m --limit 10
seams users show ada

const shown = await seams.keys.show(key.id)
await seams.keys.cap(key.id, { capMicros: "10000000" })
const user = await seams.users.show("ada")

shown = seams.keys.show(key.id)
seams.keys.cap(key.id, cap_micros="10000000")
user = seams.users.show("ada")

Freeze and revoke

seams users freeze ada
seams users unfreeze ada
seams keys revoke key_01J8Q…0x2m --yes

await seams.users.freeze("ada")
await seams.users.unfreeze("ada")
await seams.keys.revoke(key.id)

seams.users.freeze("ada")
seams.users.unfreeze("ada")
seams.keys.revoke(key.id)

Key shape

Field	Meaning
`keyPrefix`	`ak_<code>_<six>`, the leader, safe to display
`lastFour`	The last four characters, for recognition
`revokedAt`	Set on revocation; the row stays as evidence

Revoked keys are still listed. A key that vanishes on revocation takes the evidence with it.