# CybSin client API v1 — reference

Base URL: `https://cybsin.com` (or the URL the user configured). JSON bodies.
Every call: header `X-App-Key: cs_app_…`. Authenticated calls: `Authorization: Bearer <user token>`.

## Status

`GET /api/v1/app/status` → `{"app","state":"trial|paid|expired|suspended","active":bool,"days_left","pairing_ttl":600,"max_frame_bytes":4194304}`

## Accounts (end users, scoped to the application)

`POST /api/v1/register`
```json
{"email":"ana@example.com","password":"at least 8 chars",
 "device":{"name":"Ana's iPhone","platform":"ios","model":"iPhone16,2","os_version":"18.1",
           "vendor_id":"E621E1F8-C36C-495A-93FC-0C247A3E6E5F","bundle_id":"com.example.notedrop",
           "app_version":"1.0.3","locale":"fr-CA"}}
```
→ `201/200 {"token":"64 hex","device_id":12}` · 409 email exists in this app · 403 identity mismatch · 429 burst

`POST /api/v1/login` same body → `{"token","device_id"}` · 401 bad credentials

`GET /api/v1/me` → `{"email","created","app","plan"}` · `POST /api/v1/logout` → `{"ok":true}`

Tokens never expire by themselves; store them in Keychain / Keystore / OS credential store.
One token per sign-in, bound to the device given in the body.

## Devices

`POST /api/v1/devices` (device object) → `{"device_id"}` — registers or refreshes; matching by vendor_id / android_id / mac, else by name+platform.
`GET /api/v1/devices` → `{"devices":[{id,name,platform,model,os_version,bundle_id,app_version,created,last_seen}]}`

Device fields: `name*`, `platform*` (ios|android|macos|windows|linux|web), `model`, `os_version`, `vendor_id`, `android_id`,
`mac` (desktop only), `hostname`, `os_user`, `bundle_id`, `app_version`, `locale`. Server adds user agent, first/last IP.

## Pairing (same user, same app)

`POST /api/v1/pair/new` `{"device_id":12}` (optional) →
```json
{"code":"429183","session_id":"…","expires_in":600,"qr":"cybsin://pair?server=https://cybsin.com&code=429183&app=cs_app_…"}
```
`POST /api/v1/pair/join` `{"code":"429183","device_id":13}` → `{"session_id":"…"}` · 404 unknown/expired · 403 other user's code · 402 plan inactive

QR URI: `cybsin://pair?server=<url>&code=<6 digits>&app=<app_key>`. Scanning it pre-fills server + code on the guest.

## Relay

`WS /ws/relay/{session_id}?token=<user token>&role=host|guest&app_key=cs_app_…&device_id=12`

- Exactly one host (creator of the code) and one guest.
- Server → both: `{"t":"joined"}` when both present. Then verbatim forwarding of every frame.
- Server control frames: `{"t":"joined"}`, `{"t":"expired"}`, `{"t":"peer_left"}`, `{"t":"error","code":"payment_required","state":"expired"}`.
- Close codes: 4401 bad token/role/key · 4402 payment required · 4404 unknown/expired session · 4408 timed out · 4409 slot taken.
- Binary frames ≤ 4 MiB. Frames before `joined` may be lost. Nothing stored.
- Metadata of each session (devices, IPs, user agents, times, frames, bytes, end reason) goes to the developer's connection log.

## Errors

JSON `{"detail": string | {"code","message",…}}`. Codes: `payment_required` (402), `app_identity_mismatch` / `app_identity_required` (403).

## Developer API (Bearer cs_dev_…, never in a client)

| | |
|---|---|
| `GET /api/dev/v1/me` | developer identity |
| `GET /api/dev/v1/apps` · `POST /api/dev/v1/apps {name,description,platforms[],bundle_ids[],website,strict_identity}` | list / create (returns app_key + app_secret) |
| `GET /api/dev/v1/apps/{id}` · `PATCH /api/dev/v1/apps/{id}` | read / update |
| `POST /api/dev/v1/apps/{id}/rotate?what=key|secret` | rotate |
| `GET /api/dev/v1/apps/{id}/devices|connections|events|users?limit=` | registry, log, events, users |
| `POST /api/dev/v1/apps/{id}/test-user {email?,password?}` | test credentials + token |
| `GET /api/dev/v1/apps/{id}/billing` | plan, price, checkout_url or manual instructions, payments |
| `GET /api/dev/v1/guide?platform=swift` | this skill + platform file (public) |

## MCP

`https://cybsin.com/mcp`, Streamable HTTP (stateless JSON-RPC 2.0), header `Authorization: Bearer cs_dev_…`.
Tools: `cybsin_integration_guide` (public), `cybsin_list_apps`, `cybsin_create_app`, `cybsin_get_app`, `cybsin_update_app`,
`cybsin_rotate_key`, `cybsin_list_devices`, `cybsin_list_connections`, `cybsin_list_events`, `cybsin_create_test_user`,
`cybsin_billing`, `cybsin_health`.

Claude Code: `claude mcp add --transport http cybsin https://cybsin.com/mcp --header "Authorization: Bearer cs_dev_…"`
