# Space Context auth.md

How AI agents and the tools they run get access to Space Context. The audience is agents acting **for a person who has a Space Context account** (the same account as the iPhone app). There is no anonymous access to anyone's spaces.

## 1. MCP (assistants such as Claude, ChatGPT, Cursor)

- Server: `https://mcp.spacecontext.app/mcp` (Streamable HTTP).
- Authorization: OAuth 2.1 with dynamic client registration and client ID metadata documents.
  - Authorization server metadata: https://mcp.spacecontext.app/.well-known/oauth-authorization-server
  - Protected resource metadata: https://mcp.spacecontext.app/.well-known/oauth-protected-resource/mcp
- The person signs in (Apple, Google or an emailed code) and chooses what the connection may do: read spaces (always), see sensitive values (opt-in), scan spaces and spend their balance (opt-in). The connection gets a key of its own, revocable in the console.

## 2. Terminal sign-in (CLIs, local tools)

Device authorization, RFC 8628 style:

1. `POST https://api.spacecontext.app/v1/auth/device` with `{"name": "<what you are>", "mode": "live" | "test"}` → `device_code`, `user_code`, `verification_url`, `interval`.
2. Show the person `user_code` and the console URL. They type the code themselves (it is never put in a link) and approve.
3. Poll `POST https://api.spacecontext.app/v1/auth/device/token` with `{"device_code": "…"}` every `interval` seconds: `AUTHORIZATION_PENDING` until approved, then the API key (once).

`npx spacecontext login` and the SDK's `deviceSignIn()` do exactly this.

## 3. API keys

- Created by the person in the console: https://spacecontext.app/developers/console/keys/
- `sc_test_…`: free, the demo space only. `sc_live_…`: the person's spaces; scans are paid from their prepaid balance.
- Scopes: `spaces:read`, `scans:read`, `scans:write`, and opt-in `spaces:sensitive` (passwords, codes, narration). Optional monthly spending cap per key.

## 4. Agents without an account (x402)

An agent with a wallet holding USDC on **Base** or **Solana** needs no person, console or card. `POST https://api.spacecontext.app/v1/agent/credits` (body optional: `{"amount_cents": 100}` is $1, one live scan, up to 50 000) answers `402` with `PAYMENT-REQUIRED` (x402 v2, scheme `exact`): one option per network, Base (`eip155:8453`) then Solana (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`). The same call again with `PAYMENT-SIGNATURE` and the same body opens a technical account for the paying wallet and returns its live API key once, with the credit (one cent for one cent, never expires). The facilitator pays the network fee: the wallet needs only USDC. Any x402 v2 client works (`@x402/fetch` with `@x402/evm` or `@x402/svm`); stock clients cap a payment at $1 unless their `spendControls` are raised. Guide: https://spacecontext.app/developers/docs/account/agent-payments/

## Using a credential

```http
GET https://api.spacecontext.app/v1/spaces
Authorization: Bearer sc_live_…
```

Keys go only in the `Authorization` header, only to `https://api.spacecontext.app`. Never put a key in a URL. A revoked key answers `401 INVALID_TOKEN`.

More: https://spacecontext.app/developers/docs/account/api-keys/ · contract https://api.spacecontext.app/v1/openapi.json