Developer documentation
CybSin gives a multi-device application three things: user accounts, pairing, and a blind encrypted relay. You keep your own protocol; it runs inside the tunnel.
The model
- Application — what you register. Has a public
app_key(cs_app_…) that every client sends. Billed per application. - User — an end user of your application. Created with
/register, scoped to the application. The same email in two applications is two unrelated users. - Device — an instance of your app a user signed in from. Reported identity (platform, model, identifiers, bundle id) is stored for security and shown in your console.
- Pairing — a 6-digit code (10 minutes) that links two devices of the same user into a relay session.
- Relay — a WebSocket pipe between the two devices. Frames are forwarded verbatim; the server never decrypts.
Register your application
Create a developer account, then register an application. Declare its bundle identifiers so the key is bound to your app. Copy the key.
Alternatively let your AI assistant do it through the MCP (cybsin_create_app).
Trial: 14 days with every feature. Then 10 USD/month, billed yearly (120 USD/year) per application.
Keys & tokens
| Credential | Where | Used for |
|---|---|---|
X-App-Key: cs_app_… | header on every /api/v1 call; app_key= query on the WebSocket | identifies the application; safe to ship in binaries |
Authorization: Bearer <user token> | header after /register or /login; token= query on the WebSocket | identifies the end user on this device |
Authorization: Bearer cs_dev_… | /api/dev/v1 and /mcp | you, the developer; never in a client |
cs_sec_… | console only | reserved for server-side features |
Base URL: https://cybsin.com. All bodies are JSON. Interactive explorer: /api/swagger.
Accounts
Plan state of the application (active, state, days_left). Call it at launch to show a clear message when the plan lapsed.
{"email":"ana@example.com","password":"≥ 8 chars",
"device":{"name":"Ana's iPhone","platform":"ios","model":"iPhone16,2","os_version":"18.1",
"vendor_id":"E621E1F8-…","bundle_id":"com.example.notedrop","app_version":"1.0.3","locale":"fr-CA"}}
→ {"token":"…","device_id":12} 409 if the email exists in this application
Same body. device is optional but recommended: it registers or refreshes the device and binds the token to it. 401 on bad credentials, 429 on bursts.
Devices
Register or refresh the current device (same object as above). Returns device_id. Fields you can report:
| Field | Source |
|---|---|
name, platform | required; platform ∈ ios, android, macos, windows, linux, web |
model, os_version, locale, app_version | OS APIs |
vendor_id | iOS/macOS identifierForVendor (stable per vendor per device) |
android_id | Settings.Secure.ANDROID_ID |
mac | desktop only — iOS and Android do not expose MAC addresses to apps |
hostname, os_user | desktop |
bundle_id | your bundle id / package name / desktop app id — required when the application uses strict identity |
The server adds user agent, first and last IP, and timestamps. Everything appears in your console and the developer API.
Pairing
{"device_id":12} (optional; defaults to the device bound to the token)
→ {"code":"429183","session_id":"…","expires_in":600,
"qr":"cybsin://pair?server=https://cybsin.com&code=429183&app=cs_app_…"}
{"code":"429183","device_id":13}
→ {"session_id":"…"} 404 unknown/expired · 403 code belongs to another user
Pairing is deliberately same user, same application. Both devices sign in with the same end-user account; the code only works there. Show the QR string as a QR code so the other device can scan it.
Relay
- One host slot (the side that created the code) and one guest slot. A second connection to a taken slot is closed with 4409.
- When both are present the server sends the text frame
{"t":"joined"}to both. From then on every frame — binary or text — is forwarded verbatim to the peer. - Server control frames:
{"t":"joined"},{"t":"expired"}(TTL ran out before the peer came),{"t":"peer_left"},{"t":"error","code":"payment_required"}. - Close codes: 4401 bad token/role/key · 4402 payment required · 4404 unknown or expired session · 4408 timed out waiting · 4409 slot taken.
- Binary frames ≤ 4 MiB. The relay is a pipe, not a queue: nothing is stored, frames sent before
joinedmay be lost. - The session's metadata (devices, IPs, times, bytes, frames, end reason) is written to your connection log.
Errors & the 402
Errors are JSON {"detail": …}. When the application's plan is not active, pair/new, pair/join answer 402 with
{"detail":{"code":"payment_required","state":"expired",…}} and the relay closes with 4402. Sign-in still works. Handle it with a human message
("this app's connection service needs renewal") and never retry in a loop.
End-to-end encryption (byte-exact)
The relay forwards anything. To interoperate with the CybSin trust model — and with the reference clients — implement exactly this:
- On
joined, each side generates an ephemeral X25519 key pair and sends its 32-byte public key as one binary frame. - Derive the session key:
key = HKDF-SHA256(ikm = X25519(our_priv, their_pub), salt = pairing_code_ascii, # the 6 ASCII digits info = "cybsin-v1", length = 32) - Encrypt every subsequent frame with ChaCha20-Poly1305 (IETF, 12-byte nonce). Nonces are implicit, never sent:
nonce (12 bytes) = [direction, 0, 0, 0, counter_u64_be] direction: host = 0x01, guest = 0x02 counter: starts at 0, +1 per frame sent in that direction wire = ciphertext || 16-byte Poly1305 tag (no associated data) - WebSocket ordering keeps the counters in sync. Any decryption failure is a fatal session error: close, never retry with another counter.
Fingerprint (SAS)
fp = SHA-256(host_pub || guest_pub) # host key first on both sides
sas = format("%02X%02X · %02X%02X", fp[0], fp[1], fp[2], fp[3]) # e.g. "A7F3 · 9C21"
Show it on both screens; if they differ the user abandons the session. Reference implementations in Swift (CryptoKit), Rust and Python are in the skill.
Key identity
Declare your bundle identifiers in the console. With strict identity on, a device reporting another bundle id gets 403 app_identity_mismatch
and an event is logged; a device reporting none gets 403 app_identity_required. The console shows how many distinct identifiers a key has seen.
Rotate the key if it leaks; every old copy stops immediately.
Developer API
Bearer cs_dev_… from Account. Same operations as the MCP:
GET /api/dev/v1/me | who you are |
GET|POST /api/dev/v1/apps · GET|PATCH /api/dev/v1/apps/{id} | applications (keys, plan, bundle ids) |
POST /api/dev/v1/apps/{id}/rotate?what=key|secret | rotation |
GET /api/dev/v1/apps/{id}/devices|connections|events|users | registry, log, events, users |
POST /api/dev/v1/apps/{id}/test-user | credentials + token for testing |
GET /api/dev/v1/apps/{id}/billing | plan, price, checkout link or invoice instructions |
GET /api/dev/v1/guide?platform=swift | the skill + platform code, public |