Every call to the API, the CLI and the SDK uses an API key, sent as a bearer token:
Authorization: Bearer sc_live_…Create keys in the console under API keys. The key is shown once: we store only its hash. If you lose it, revoke it and create another.
Test and live
sc_test_… | sc_live_… | |
|---|---|---|
| Sees | The demo space spc_demo and spaces created with test keys | Your real spaces |
| Scans | Free, complete at once, always return the demo content | Real analysis; the account’s free scan first (one per card), then paid from your balance |
| Models | None are called | Vision and language models |
| Webhooks | Sent to endpoints in test mode | Sent to endpoints in live mode |
| Card on file | Never needed | Needed for a key with scans:write |
Use test keys for development and CI; switch to a live key when you go to production. Test and live data never mix.
Scopes
| Scope | Allows | Default |
|---|---|---|
spaces:read | GET /spaces, GET /spaces/{id}, search, ask, skills, comparisons | ✓ |
scans:read | GET /scans/{id}, the event stream, GET /wallet | ✓ |
scans:write | Creating spaces and scans, uploading, starting, cancelling, deleting spaces, frame checks | ✓ |
spaces:sensitive | Wi-Fi passwords, door and alarm codes, the transcript, the owner’s own answers, past scans of app spaces | — |
A key without spaces:sensitive reads the redacted document. For spaces scanned with the app, it reads them only once they have been screened; see Security and privacy. A request that needs a missing scope answers 403 INSUFFICIENT_SCOPE.
Give an agent the narrowest key that does the job: spaces:read alone for an assistant that only answers questions.
Live keys that can scan need a card
A live key with scans:write (one of the default scopes) can be created only once your account has a card on file: add one in the console under Billing → Add a card. Stripe saves it and nothing is charged; scans are still paid from your balance, after the account’s free scan if it has one (one free scan per card). See Billing.
Without a card, creating such a key answers 402 PAYMENT_METHOD_REQUIRED, whether you create it in the console, approve it for spacecontext login or allow scanning when you connect an assistant. Test keys and live keys without scans:write (read-only) never need a card. Removing the card later does not revoke the keys you already have.
The same rule applies when a live scan is created or starts, and to a live frame check (POST /frames/check), whoever asks (a key, the console or an assistant): an account with no card saved and no top-up paid gets 402 PAYMENT_METHOD_REQUIRED before any upload link is given, and nothing is charged, its free scan included. Test scans never need a card. A test scan’s video is at most 95 MB: it is uploaded through the API and nothing of it is kept (its result is the demo).
Monthly spending cap
A live key can have a monthly cap in US dollars. Scans that would take the key’s spending for the calendar month over the cap are refused with 402 SPENDING_CAP_REACHED; other keys are not affected. The cap counts what the key spends on scans, not your whole balance.
Revoking
Revoke in the console takes effect at once: the next call with the key answers 401 INVALID_TOKEN.
Keys created by the MCP connector carry the name of the assistant and an MCP badge; they have scans:write only if you allowed scanning when you connected (which needs a card on file). Revoking one disconnects that assistant: it asks you to sign in again on its next request. Connecting the same assistant again replaces its previous key automatically. Keys created by spacecontext login are named CLI · … after the terminal that asked.
Limits
Up to 20 active keys per account.