Developer API

This page fully specifies KeyLockr SSO, end-to-end encrypted AppData, optional Access Point (AP) authorization, and backend verification. Every required wire format, cryptographic rule, error, and example is included.

Overview

Delegated SSO quick start

1. The App calls its own backend /kl/login/start.
2. The App opens the backend-provided deep link and waits for its registered Universal Link/App Link (recommended) or restricted custom-scheme callback.
3. The App sends its private finish_secret and opaque assertion to its own backend /kl/login/finish.

Register a service

my.keylockr.app/developer

An app_tag is a public identifier, not a client secret. App Attest is not part of this flow, and there is no app_attest_challenge API.

Keys and environments

Key endpoints return a standard-Base64 32-byte public key. With client ownership, every physical App/Browser persistently retains its own X25519 box keypair and creates an Ed25519 signing keypair for the current login. After a successful normal logout, it must delete or replace the signing keypair while retaining the box keypair. Even when the third-party backend has a registered service key, the client never receives or uses the backend enc_sk. A backend-owned logical deployment persistently retains one shared X25519 box keypair and maintains a current signing credential per Safe; it registers the X25519 enc_pk in MyDeveloper. Transmit only public keys; private keys never leave their owner.

sign_pk, sign_sk = nacl.sign.keyPair() // 32-byte pk, 64-byte sk
enc_pk, enc_sk   = nacl.box.keyPair()  // 32-byte pk, 32-byte sk

Delegated SSO v1

/start must run immediately before the App shows a QR or opens the deep link. From one start_wall_time snapshot, the backend derives a 600-second challenge deadline and a 720-second retention deadline, using independent CSPRNG outputs for the public challenge and private finish_secret.

POST your-backend.example/kl/login/start

// Cache-Control: no-store
{
  deeplink: string,        // keylockr://sso-request?request=...
  finish_secret: string,   // private, 32-byte base64url
  request_digest: string,  // exact SHA-256(auth_request)
  expires_at: number       // Unix seconds
}

The signed request uses a fixed 11-field MessagePack claim, the current Ed25519 key, and its kid. The challenge is a public transaction ID, not an authorization credential; only the original App holding the finish_secret can finish. The request also signs the app_tag, return URL, capabilities, optional client public keys, device name, and AP scopes.

Delegated v1 accepts client ownership only and requires both client_sign_pk and client_enc_pk. Backend-owned services have no delegated-request signing credential in this wire version and must use the legacy advanced handshake below; an X25519 encrypt_pk_base64 is not a signing key.

POST your-backend.example/kl/login/finish
{
  finish_secret: string,
  backend_assertion: string
}

// After offline KL seal + box + claim verification and atomic Redis completion:
{
  session_result: object,
  safe_id: string,
  user_nickname: string
}

Finish does not call KeyLockr or /app_verify. Pending/completed state lives only in Redis. An exact secret/assertion retry returns the same session; mismatches and expired replays return the same generic authentication failure. Before activating the session, the login client must show the verified nickname and full Safe ID for explicit confirmation. Safe ID, not nickname, is the stable identity.

KeyLockr Mobile internally calls app_delegated_info and app_delegated_approve. These Safe KPS actions are not third-party App/backend APIs.

Delegated v1 does not permit data_deferred or a third-party App fallback to KeyLockr. Any inline overflow ends with app_auth_result_too_large. Rejection is exactly keylockr_result=cancel and must not call finish.

Legacy advanced: capability handshake

POST https://api.keylockr.app/v3/handshake
Content-Type: application/octet-stream
Accept: application/octet-stream

// MessagePack, not JSON and not KPS-encrypted
{
  sign_pk: Uint8Array,          // exactly 32 bytes
  enc_pk?: Uint8Array,          // 32 bytes for client ownership; ignored for backend
  app_tag: "your_effective_tag",
  name?: "Work MacBook",        // required for AppData or AP
  app_data?: true,
  ap?: true,
  requested_scopes?: ["2fa"]    // AP only; non-empty when present
}
// -> { _res: "ok", tmp_id: string }

The sign_pk is always required and exactly 32 bytes. With sso_key_owner=client, enc_pk is required and exactly 32 bytes; KL does not override the request key even when encrypt_pk_base64 is registered. With sso_key_owner=backend, KL ignores any supplied or omitted enc_pk and uses only a valid registered 32-byte X25519 service key; a missing or invalid key never falls back.

After trimming, name must contain 1–255 Unicode characters. With ap=true, omitting requested_scopes requests full AP; a restricted service must send a non-empty approved subset. Never send scopes without ap; only sso_key_owner=client may request AP, regardless of whether a separate service key exists.

The tmp_id and its temporary key/capability state live for 3600 seconds. Check _res before reading every HTTP response, even when its HTTP status is 200.

WebSocket, QR, and authorization result

message = utf8("tmp.{tmp_id}.{unix_seconds}")
signed  = nacl.sign(message, sign_sk) // 64-byte signature || message
sig     = base64url_without_padding(signed)

wss://api.keylockr.app/v3/ws?sig={urlencoded_sig}

sso://login?tmp_id={tmp_id}
keylockr://sso?tmp_id={tmp_id}

keylockr://sso?tmp_id={tmp_id}&return_url={percent_encoded_absolute_uri}

// Decrypted KPS frame:
header.from = "app_auth_result"
body = {
  _res: "ok",
  status: "done",
  tmp_id: string,
  app_id: string,
  safe_id: string,
  capabilities: string[],
  user_nickname: string,
  user_enc_pk: Uint8Array,
  ap_access?: { full_access: boolean, scopes: string[] },
  account_key_for_ap?: Uint8Array,
  data_filekey?: Uint8Array,
  data_plain?: Uint8Array,
  data_encrypted?: Uint8Array,
  data_deferred?: true,
  ver?: string
}

// Terminal completion when the frame cannot be compacted:
body = {
  _res: "ok",
  status: "error",
  tmp_id: string,
  code: "app_auth_result_too_large"
}

Completion may arrive through the temporary WebSocket or a native callback; there is no HTTP polling. After a brief disconnect, reconnect with the same keypair while tmp_id remains valid to replay the completed result.

The completion KPS shared by WebSocket and callback is limited to 12 KiB. data_deferred=true is set only when the Safe supplied a client filekey and AppData content was actually omitted; retain data_filekey and ver, then call app_get_data. Without a client filekey, an older Safe result that would exceed the limit omits only the currently unusable data_encrypted, retains data_plain and ver, and does not set data_deferred; call app_req_filekey for the filekey, then obtain the latest encrypted content from app_filekey_result or app_get_data. A result still over the limit after trimming terminates with app_auth_result_too_large.

The AP Account Key format is nonce(24) || nacl.box(AK, nonce, client_enc_pk, safe_enc_sk). Open it with user_enc_pk and the client enc_sk, require 32 bytes, and never log or upload it.

// Existing AP only: recover a locally lost Account Key.
action: "app_req_account_key"
body: {}

{
  _res: "ok",
  account_key_for_ap: Uint8Array,
  safe_enc_pk: Uint8Array
}
// or { _res: "ok", status: "not_available" }

not_available means the binding never completed Account Key delivery; delete it and authorize again because there is no background repair. A non-AP binding receives app_not_ap.

KPS crypto protocol

Every WebSocket frame and POST /v3/ App action uses binary MessagePack KPS.

Client to server

{
  kps: {
    id: "tmp.{tmp_id}" | "app.{app_id}",
    app_ver: string,
    box: Uint8Array,
    n: Uint8Array,      // exactly 24 random bytes
    raw?: Uint8Array[]
  },
  seal: Uint8Array
}

inner = msgpack({
  header: { ts: unix_seconds, to: action },
  body: action_params
})
box  = nacl.box(inner, n, server_enc_pk, client_enc_sk)
seal = nacl.sign(
  sha256(canonical_msgpack_with_sorted_map_keys(kps)),
  client_sign_sk
)

Server to client

{
  kps: {
    box: Uint8Array,
    n: Uint8Array,
    raw?: Uint8Array[]
  },
  seal: Uint8Array
}

// After seal verification and box.open:
{
  header: { ts: number, from: string },
  body: {
    _res: "ok" | "err",
    code?: string,
    msg?: string
  }
}

Outer, kps, inner, and header are closed core schemas: reject unknown or duplicate fields, trailing values, invalid UTF-8, wrong types, and oversized values. A general action body is an extension boundary: validate _res, required fields, types, and conditions, then ignore unknown fields. Reject unknown action fields only when that action is explicitly documented as exact/closed.

The receive order is fixed: strictly decode outer/core without restoring raw, verify the seal and canonical KPS hash, validate the 24-byte nonce and open the box, strictly decode inner/header, recursively validate every field__ index, raw binary type, bound, and field/field__ collision, materialize the logical body, then validate the action schema and body._res. Abort on any failure.

Raw is only for already encrypted blobs: the seal protects integrity, but the box does not hide it. Even when an unknown extension field will be ignored, its placeholder must pass full validation before materialization.

Complete AppData flow

AppData actions use the app.{app_id} KPS identity. KeyLockr stores only an encrypted filekey and application ciphertext and never holds the plaintext filekey.

1. Use the authorization result; request a filekey only when needed

A current Safe's initial app_auth_result directly supplies data_filekey, ver, and existing data_encrypted when it fits the completion limit; a new namespace may be empty. After validation, open the filekey and use that data immediately. If data_deferred=true, call app_get_data directly. Neither path needs a second phone unlock. Use app_req_filekey only when an older Safe omitted data_filekey, the local key was later lost, or a separate re-unlock is required.

For the compatibility path, connect the App WebSocket with nacl.sign("app.{app_id}.{ts}", sign_sk) and register an app_filekey_result waiter before sending the action, so a fast approval cannot be missed.

action: "app_req_filekey"
body: {}

// Immediate or polling KPS response:
{
  _res: "ok",
  status: "done" | "safe_auth_required" | "denied",
  data_filekey?: Uint8Array, // done only
  ver?: string              // done only
}

// App WebSocket completion:
header.from = "app_filekey_result"
body = {
  _res: "ok",
  status: "done" | "denied",
  data_filekey?: Uint8Array,
  data_enc?: Uint8Array,
  ver?: string
}

A safe_auth_required status means the Safe has been notified. Wait for the push while WebSocket is available; use spaced polling only after disconnect or timeout. Polling done does not include data_enc, so call app_get_data next.

2. Open data_filekey

// MessagePack envelope; new data uses full names.
{
  encFileKey: Uint8Array,   // 48 bytes
  nonceForKey: Uint8Array,  // 24 bytes
  nonceForData: Uint8Array, // 24 bytes; v1 read fallback only
  apEncPk: Uint8Array       // 32-byte sender pk
}

// Read-only legacy aliases:
{ k, nk, nd, p }

file_key = nacl.box.open(
  encFileKey,
  nonceForKey,
  apEncPk,
  client_enc_sk
)
// file_key must be exactly 32 bytes.

Readers normalize all four fields with fullName ?? legacyShortName and validate lengths. nonceForData is only for legacy v1 reads and must never be used for new writes.

3. Read and decrypt

action: "app_get_data"
body: {}

// KPS response:
{
  _res: "ok",
  file_id: string,
  ver: string,
  data_plain: Uint8Array,
  data_encrypted: Uint8Array
}

The data_plain field is Safe-created MessagePack metadata {name, app_tag} and is not third-party mutable. Store application data only in data_encrypted.

// Every new write is v2:
nonce = randomBytes(24)
data_encrypted =
  nonce || nacl.secretbox(msgpack(application_data), nonce, file_key)

// Read:
1. If length >= 40, try nonce-prefix v2 and verify its MAC.
2. Only if v2 fails, try the whole blob as v1 with nonceForData.
3. If both fail, abort. Never parse unauthenticated bytes.

4. Write with version CAS

action: "app_set_data"
body: {
  ver: string,          // exact latest value
  data_enc: Uint8Array  // complete v2 nonce-prefixed ciphertext
}

// KPS response:
{ _res: "ok", file_id: string, ver: string }

ver is mandatory. Each operation may read once after the initial write and send at most one more CAS write; a second conflict terminates. For a single-slot payload such as a 4S recovery key, an authoritative value exactly equal to the intended value is idempotent completion: adopt the latest ver without writing. A different value fails closed; never overwrite, concatenate, or choose by timestamp. Only a payload with a defined deterministic field-level merge may merge once and retry once.

Binding lifecycle

Update the local display name

action: "app_update"
body: {
  name?: string,
  name_enc?: Uint8Array
}

// -> { _res: "ok", name?: string, name_enc?: Uint8Array }

At least one of name or name_enc is required. An App may update only its own name, not AP scopes. name_enc uses the AP Account Key nonce(24) || secretbox format; an SSO/AppData client without the Account Key must not fabricate it with another key.

Log out while retaining the binding

action: "app_logout"
body: {}

// -> { _res: "ok", status: "logged_out", app_id: string }

app_logout is SSO-only and authenticates the caller with the current sign_pk. On success, the server clears only that row's sign_pk; the app_id, enc_pk, AppData file, and capabilities remain. The caller then deletes or replaces its local signing keypair while retaining the encryption keypair. After the Safe approves the same enc_pk with a new sign_pk, the server reactivates that same row; every old-credential request fails while logged out. AP clients must not use this action.

Permanently revoke the current binding

action: "app_del"
body: {}

// -> { _res: "ok", id_deleted: string }

Backend verification and service keys

POST /v3/app_verify

Content-Type: application/json

{
  app_tag: "your_effective_tag",
  app_id: string,
  safe_id: string,
  sign_pk: string // standard base64, same 32-byte Ed25519 pk as handshake
}

// Normal mismatch:
{ _res: "ok", valid: false }

// Verified:
{ _res: "ok", valid: true, nickname: string }

// Allowlist configuration/rejection:
{ _res: "err", code: "server_verification_disabled" | "ip_not_allowed",
  request_ip: string }

This endpoint is for App/Browser claims with sso_key_owner=client. The caller must be in server_ips. Check _res first; an IP, configuration, or parameter error with _res=err is not valid=false. request_ip is the canonical IPv4/IPv6 used by KL; an invalid source is returned as an empty string rather than reflected. Add a non-empty value in MyDeveloper only after confirming it is your fixed egress. KL never returns the full allowlist. After verification, have your backend issue its own short-lived session; app_id is not a bearer token. The service may separately register encrypt_pk_base64 for data encrypted to the backend, but the App still uses only its own enc_pk/enc_sk; never give the backend enc_sk to the App.

POST /v3/sso_user_pubkey

Content-Type: application/json

{ app_tag: string, safe_id: string }

{ _res: "ok", found: false }
// or
{ _res: "ok", found: true, sign_pk: string } // standard base64 Ed25519 pk

Only an approved plugin backend with server_ips, plugin_approved, and plugin_api_url may call this endpoint. found=false intentionally does not reveal whether approval, binding, or a key is missing.

GET https://my.keylockr.app/svc_pk/{app_tag}

{ _res: "ok", pk_base64: string }

This endpoint only publishes MyDeveloper encrypt_pk_base64; it neither publishes nor infers sso_key_owner. A non-empty value serves service-to-service profile/data encryption independently of plugin approval and handshake ownership. Only when sso_key_owner=backend is separately selected does KL ignore the request enc_pk and require the server to retain the matching enc_sk. Client ownership may keep a non-empty service key while the App handshake still uses its own key.

GET https://my.keylockr.app/svc_info/{urlencoded_app_tag}

{ _res: "ok", title: string }
// Unknown or invalid identity:
{ _res: "err", code: "invalid svc" }

This public JSON endpoint lets third-party login pages retrieve the authoritative MyDeveloper display name. Put app_tag in one path segment using UTF-8 percent-encoding. The response contains only title; it does not return url, description, sso_key_owner, approval state, or private configuration. Treat the title as untrusted text, never inject it as HTML, and cache it for the lifetime of the current service configuration. On error, use your own product fallback name. The endpoint is IP-rate-limited; handle rate-limit responses with the standard try_later rules.

Errors, retries, and troubleshooting

Every wait and retry requires a local timeout and cancellation path. Reply to a KPS ping event with KPS pong. Never log private keys, the Account Key, filekeys, or decrypted AppData.

API reference

The authoritative closed JSON schema for /web/* alias login and registration is downloadable separately. Consumers must implement from the document rather than inspect KeyLockr source to infer fields.

Web Auth API.md

app_scan_info, app_add, safe_*, and general file_* actions belong to the Mobile Safe authorization/data flow and are not called by third-party SSO/AppData clients.

Runnable Go sample

delegated.go is the recommended flow. It implements signed /start requests, a strict callback parser, offline KL assertion verification, the finish_secret check, and an atomic completion-store contract. The canonical fixture is shared by 9305, iOS, Android, and this example. main.go/kps.go/kps_decode.go/appdata.go retain only the legacy direct-client compatibility flow; delegated never falls back automatically.

# Delegated fixture and finish verification
env GOWORK=off go test ./...

# Legacy direct-client pure SSO compatibility example
go run . -app-tag YOUR_APP_TAG

# SSO + AppData read
go run . -app-tag YOUR_APP_TAG -app-data

# AppData read plus demo CAS write
go run . -app-tag YOUR_APP_TAG -app-data -write "hello"

# Restricted AP
go run . -app-tag YOUR_APP_TAG -ap -scopes 2fa

# Full AP
go run . -app-tag YOUR_APP_TAG -ap

The delegated example never calls app_verify. In the legacy compatibility command, app_verify succeeds only from a fixed egress IP allowed by server_ips. No example prints private keys, finish secrets, assertions, complete callbacks, the Account Key, filekeys, or decrypted data.

Pre-production completion checklist

Completing this checklist covers every protocol requirement needed to implement and ship independently.