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

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

CredentialWhereUsed for
X-App-Key: cs_app_…header on every /api/v1 call; app_key= query on the WebSocketidentifies the application; safe to ship in binaries
Authorization: Bearer <user token>header after /register or /login; token= query on the WebSocketidentifies the end user on this device
Authorization: Bearer cs_dev_…/api/dev/v1 and /mcpyou, the developer; never in a client
cs_sec_…console onlyreserved for server-side features

Base URL: https://cybsin.com. All bodies are JSON. Interactive explorer: /api/swagger.

Accounts

GET /api/v1/app/status

Plan state of the application (active, state, days_left). Call it at launch to show a clear message when the plan lapsed.

POST /api/v1/register
{"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
POST /api/v1/login

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.

GET /api/v1/me  ·  POST /api/v1/logout

Devices

POST /api/v1/devices

Register or refresh the current device (same object as above). Returns device_id. Fields you can report:

FieldSource
name, platformrequired; platform ∈ ios, android, macos, windows, linux, web
model, os_version, locale, app_versionOS APIs
vendor_idiOS/macOS identifierForVendor (stable per vendor per device)
android_idSettings.Secure.ANDROID_ID
macdesktop only — iOS and Android do not expose MAC addresses to apps
hostname, os_userdesktop
bundle_idyour 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.

GET /api/v1/devices

Pairing

POST /api/v1/pair/new
{"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_…"}
POST /api/v1/pair/join
{"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

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

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:

  1. On joined, each side generates an ephemeral X25519 key pair and sends its 32-byte public key as one binary frame.
  2. 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)
  3. 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)
  4. 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/mewho 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|secretrotation
GET /api/dev/v1/apps/{id}/devices|connections|events|usersregistry, log, events, users
POST /api/dev/v1/apps/{id}/test-usercredentials + token for testing
GET /api/dev/v1/apps/{id}/billingplan, price, checkout link or invoice instructions
GET /api/dev/v1/guide?platform=swiftthe skill + platform code, public