Protocol reference · v1 · current source

A public UUID.
Private contents.

Build a compatible client or host your own service. The default app service is https://cloud.getvouchers.app. Configuration, credentials and voucher codes are encrypted on the device before transmission.

1. Register without a manual service token.

Cloud use is optional. When a user chooses to connect a profile, the client checks GET /v1/info. A compatible response identifies service: "unifi-api", api: "v1", profile_registration: "open" and the feature names permanent_sharing, device_grants, password_recovery, live_journal and profile_sync. Closed or legacy token-only installations reject this normal app flow with an explanatory error.

The client creates a random UUID v4, a random 32-byte profile root key and a separate random 32-byte owner capability. It durably stores its keys before uploading. The service confirms the UUID in its creation response; that UUID identifies the encrypted profile on every device. It is a public identifier, never an authorization or decryption secret.

Encrypt the configuration for revision 1, then send this JSON to POST /v1/profiles, without an Authorization header on an open installation:

{
  "id": "CLIENT_GENERATED_UUID_V4",
  "owner_hash": "BASE64URL_SHA256_OF_OWNER_CAPABILITY_STRING",
  "envelope": {
    "version": 1,
    "algorithm": "xchacha20poly1305",
    "nonce": "BASE64URL_24_BYTES",
    "ciphertext": "BASE64URL_CIPHERTEXT_AND_TAG"
  }
}

The root key and owner capability are excluded from this request. For later requests the client sends its profile capability as Authorization: Bearer CAPABILITY. These capabilities are generated and managed internally; the user does not enter a service token. Store only SHA-256 of the exact UTF-8 capability string in PostgreSQL, not a hash of its decoded bytes. Never put capabilities in query strings or logs.

2. Use authenticated encryption on the client.

Encode binary values as unpadded base64url. Use XChaCha20-Poly1305 with a fresh cryptographically random 24-byte nonce for every encryption and a 16-byte tag appended to the ciphertext. Do not reuse a nonce with the same key. The wire envelope is:

{
  "version": 1,
  "algorithm": "xchacha20poly1305",
  "nonce": "BASE64URL_24_RANDOM_BYTES",
  "ciphertext": "BASE64URL_CIPHERTEXT_THEN_16_BYTE_TAG"
}

Derive separate 32-byte configuration, journal and grant-note keys. Decode the root key before HKDF; salt and info are UTF-8 strings. Include the full authenticated context (AAD) exactly as shown:

config_key  = HKDF-SHA256(root_key_bytes, UTF8(profile_uuid), UTF8("unifi-api/v1/config-key"), 32)
journal_key = HKDF-SHA256(root_key_bytes, UTF8(profile_uuid), UTF8("unifi-api/v1/journal-key"), 32)
note_key    = HKDF-SHA256(root_key_bytes, UTF8(profile_uuid), UTF8("unifi-api/v1/grant-note"), 32)
owner_hash  = base64url(SHA256(UTF8(owner_capability_string)))
configuration: unifi-api/v1/config/{profile_uuid}/{revision}
voucher event: unifi-api/v1/voucher-event/{profile_uuid}/{event_uuid}
share packet:  unifi-api/v1/share/{locator}
grant note:    unifi-api/v1/grant-note/{profile_uuid}/{grant_hash}
owner recovery: unifi-api/v1/owner-recovery/2/{canonical_service_origin}/{profile_uuid}

Configuration plaintext is {schema:1, profile:…, settings:…, read_only:true}. read_only:true is a fixed constant of schema 1; it does not restrict voucher operations. The plaintext includes the connections needed by the receiving app; administrator login passwords are excluded. Journal plaintext contains the action, observation time, voucher code and associated details. Both are JSON encoded as UTF-8 before encryption. Neither plaintext belongs in an HTTP request, server log or database column. Reject unknown envelope versions, bad authentication tags, swapped profile/event contexts and rollback below the last known revision.

Use a maintained cryptographic library. References: HKDF (RFC 5869), libsodium XChaCha20-Poly1305. Download deterministic interoperability vectors. The file has five vectors: configuration, journal, sharing, recovery-v2 and the legacy version 1 recovery. Their keys and passwords are public test fixtures, never production credentials.

3. Implement the wire endpoints.

Ordinary requests/responses use JSON; streaming uses text/event-stream. Return Cache-Control: no-store and X-Content-Type-Options: nosniff. The service does not connect to UniFi controllers or create/revoke vouchers; owners and recipients do that from their own devices, straight to the controller.

MethodPathPermissionContract
GET/v1/infoPublicService identity, registration policy and supported features.
POST/v1/profilesOpen registration; no service tokenCreate {id, owner_hash, envelope}; return 201 {id, revision:1, envelope}.
GET/v1/profiles/{id}Owner or recipientRead {id, revision, envelope}.
GET/v1/profiles/{id}/statusOwner or recipientRead {id, revision}; no configuration download needed.
PUT/v1/profiles/{id}Owner{expected_revision, envelope}; atomic revision increment, 204 or 409.
DELETE/v1/profiles/{id}OwnerDelete configuration, recovery packet, shares, grants and journal.
POST/v1/profiles/{id}/sharesOwner{locator, grant_hash, claim_hash, envelope, permanent:true} plus optional single_device, ttl_seconds and note; 400 if invalid.
GET/v1/profiles/{id}/grantsOwner{items:[{hash, created_at, expires_at, expired, single_device, claimed, note}]}; oldest first.
POST/v1/shares/{locator}/claimDerived claim capability{receiver_hash}; returns the encrypted Envelope directly; decrypt it for the profile ID. A single-device code admits only its first receiver.
DELETE/v1/profiles/{id}/grants/{hash}OwnerRevoke that one sharing code and its capability; other codes keep working.
POST/v1/profiles/{id}/eventsOwner or recipientAppend {id, envelope}; exact retries are idempotent.
GET/v1/profiles/{id}/events?after=0Owner or recipient{items:[{sequence,id,envelope}], cursor}; up to 100 ordered entries.
GET/v1/profiles/{id}/events/streamOwner or recipientSSE sequence hints only; fetch encrypted pages after the current cursor.
GET/v1/profiles/{id}/recoveryRecovery capabilityReturn {version:2, kdf, envelope}, never the hash; 401 for a wrong or missing capability, 429 after repeated failures, 404 if none is configured.
PUT/v1/profiles/{id}/recoveryOwnerReplace with exactly {version:2, kdf, auth_hash, envelope}; version 1 bodies get 400.
DELETE/v1/profiles/{id}/recoveryOwnerDelete the recovery packet; copied keys remain valid.

Use 401 for invalid capabilities, without distinguishing unknown profiles. Use 404 for unavailable claims/recovery, 409 for revision conflicts or duplicate identifiers with different contents, 429 for live-connection limits and for too many failed recovery attempts, 507 when a profile, grant or journal storage limit is reached, and generic 503 errors for storage failures. Never return SQL, database URLs or credentials. Bound request bodies to 1.5 MB; encrypted configuration is at most 1 MiB, journal ciphertext 64 KiB, sharing packets 16 KiB and recovery ciphertext 8192 bytes. These limits apply after base64url decoding and include the 16-byte authentication tag. Each profile is limited to 64 sharing grants, 10,000 journal events and 10 MiB of serialized encrypted journal envelopes. Enforce these limits under the same profile-row lock across replicas; allow exact idempotent retries at capacity. DELETE /v1/profiles/{id} removes the encrypted profile, journal, grants and sharing codes, and recovery packet; the app offers it to the owner as Delete cloud data. Backups follow the operator's separate retention policy.

4. Stay in sync without overwriting concurrent edits.

Automatic sync is optional per device and starts off. When enabled, a foreground app keeps the selected profile's encrypted voucher journal subscribed even when the journal dialog is closed. It checks the authorized configuration revision about every three seconds. Owner devices automatically upload changes to the profile/controller configuration, validity presets, quick-create voucher presets and shared WiFi passphrases; every other device, owner or recipient, applies newer revisions automatically. Settings need no explicit save. Device IDs, connection recency and the selected controller are excluded from change detection. Language is a per-device preference (recipients follow the profile's language), WiFi networks hidden on a device stay hidden there, and device security and tray mode remain local.

Configuration updates use compare-and-swap: encrypt for expected_revision + 1 and update only if the stored revision still equals expected_revision. A simultaneous local and remote edit needs a visible user decision; never silently overwrite either copy. Pending local edits and encrypted outbox entries survive interruption. Owner changes while an upload is in flight are kept for a later upload.

Voucher events have stable IDs, so the same voucher and action is stored once however many devices see it:

mac      = HMAC-SHA256(journal_key, UTF8("voucher-event/{action}/{voucher_id}"))
event_id = UUID version 8 layout of mac[0..16]

Every device derives the same ID and the service stores each ID once. Record a voucher as observed at most once, and not at all if its creation or revocation is already in the journal. Events without a voucher ID use a random UUID v4. Persist each encrypted event before sending; retry the same ID with the identical envelope. Exact duplicates succeed, changed content for an existing ID returns 409, which a client treats as already recorded. Show older journals with repeated observations de-duplicated. Pages contain up to 100 records in increasing sequence order; cursors need not be contiguous. Subscribe before loading history, then fetch pages after the committed cursor, decrypt locally and reject duplicate IDs or invalid cursor order.

event: journal
id: 123
data: 123

SSE carries only a sequence hint. The service checks PostgreSQL and the grant about once per second, works across replicas and closes revoked streams. Send keepalive comments every 15 seconds, disable proxy buffering (X-Accel-Buffering: no), cap active streams at 64 per API instance and release database connections between checks. Clients bound hint lines to 4096 bytes and reconnect with backoff after interruption. Mobile background suspension is not push delivery; catch up when the app resumes. Turning sync off stops automatic reads and new cloud-log uploads without deleting existing records.

5. Share recipient access with one code per device.

The code is XXXXXXXX.YYYYYYYYYYYYYYYYYYYYYY: a random 6-byte locator encoded to 8 characters, then a random 16-byte secret encoded to 22 characters. Of the two code components, only the locator is sent to the service. The secret suffix stays on the clients.

From the decoded secret derive a wrapping key and separate claim capability with HKDF-SHA256, salt UTF-8 locator, 32-byte output, and info unifi-api/v1/share-key or unifi-api/v1/share-claim. Encode the claim capability as base64url; the server stores its string hash. Encrypt {id,key,token,minimum_revision,permanent:true} using the wrapping key. Here token is a newly generated recipient capability; it is never the owner capability. Register only the encrypted packet, locator, grant hash and claim hash. Every code has its own capability.

Three optional fields set the policy of a code. single_device:true binds it to the first device that redeems it and requires permanent:true; without it the code is reusable. ttl_seconds (60 to 31622400) ends access after that time; without it the code has no expiry. note is an Envelope of at most 2048 ciphertext bytes, encrypted with the grant-note key over the JSON {label,code}: the name the owner gave the code and the code itself. The service stores the note with the grant and cannot read it. Reject invalid values with 400. The app offers one device (the default) or several, and an end after 1, 7, 30 or 365 days or never.

The claim endpoint returns the encrypted Envelope directly. Decrypt it to obtain the profile UUID and recipient keys. Claims require a valid receiver_hash and do not consume the packet. A reusable code admits every receiver. A single-device code admits the first receiver_hash; that receiver may retry, any other gets 404. The client saves its received keys before use. The invitation QR is getvouchers://cloud?v=1&server=ENCODED_ORIGIN#CODE. Its fragment is parsed locally. When access ends, stop accepting the capability (401, close its live streams) and refuse further claims of the code. Anyone holding a reusable code can forward it.

GET /v1/profiles/{id}/grants is for owners only and returns {items:[{hash,created_at,expires_at,expired,single_device,claimed,note}]}, oldest first. Timestamps are Unix seconds; expires_at is null without an expiry, claimed is null for reusable codes and note is null if none was stored. Keep ended grants listed as expired until the owner creates the next code, then prune them. DELETE /v1/profiles/{id}/grants/{hash} revokes that one capability and its code; the others keep working. Any owner device can decrypt the notes to name the codes and display an unredeemed code again. Codes registered by older clients have no note: list them, allow revocation, but they cannot be displayed again. Revocation and expiry do not rotate the profile key; already copied keys and controller credentials cannot be recalled.

For legacy requests without permanent:true, retain the original ten-minute, first-receiver, one-use behavior. Acknowledge those only after durable client persistence with DELETE /v1/shares/{locator} using the receiver capability.

6. Restore owner access with UUID + password.

Recovery is version 2. Derive everything locally from the password, the canonical service origin and the profile UUID. The salt is deterministic, so a fresh device needs no stored value. Accept only the fixed identifier argon2id-v19-m65536-t3-p4. Passwords are at least 16 characters and at most 1024 UTF-8 bytes; a randomly generated password is preferable to a predictable phrase. See RFC 9106.

salt      = SHA256(UTF8("unifi-api/v1/owner-recovery-salt/{canonical_service_origin}/{profile_uuid}"))[0..16]
master    = Argon2id(v19, password, salt, m=65536 KiB, t=3, p=4, 32)
wrap_key  = HKDF-SHA256(master, UTF8(profile_uuid), UTF8("unifi-api/v1/owner-recovery-wrap"), 32)
recovery_capability = base64url(HKDF-SHA256(master, UTF8(profile_uuid), UTF8("unifi-api/v1/owner-recovery-auth"), 32))
auth_hash = base64url(SHA256(UTF8(recovery_capability)))

Encrypt {schema:1,id,key,token,minimum_revision} with the wrap key, where key/token are the root key and owner capability. The owner stores exactly {version:2,kdf,auth_hash,envelope}; reject version 1 bodies with 400. The password, master value, wrap key and plaintext owner keys never reach the API.

GET /v1/profiles/{id}/recovery requires Authorization: Bearer RECOVERY_CAPABILITY and returns {version:2,kdf,envelope}, never the hash. Answer 401 for a wrong or missing capability and 404 if no recovery is configured. After 10 failed attempts per profile within 15 minutes, answer 429 {"error":"too_many_attempts"} until the window passes; a success or a new PUT resets the counter. On restore, decrypt locally and authorize/decrypt the current configuration before persisting it.

The recovery QR is getvouchers://recover?v=1&server=ENCODED_ORIGIN&id=UUID. It contains only UUID and service address; the password is entered separately. Recovery grants owner cloud permissions; a sharing code grants recipient permissions. Both create and revoke vouchers from their own device.

An attacker who knows only the UUID can make rate-limited online guesses; offline guessing requires a copy of the service database. A strong password still matters. Someone who knows the UUID can temporarily pause recovery, not sync, by sending wrong guesses. Removing/changing recovery does not invalidate previously copied packets or keys. There is no operator reset or key escrow. A freshly restored device can reject revisions below its packet's minimum, but cannot detect the server withholding newer revisions. E2E encryption does not guarantee availability or prove every controller action was logged.

Legacy: packets stored as version 1 ({version:1,kdf,salt,envelope}, random salt, AAD unifi-api/v1/owner-recovery/1/…) remain readable by UUID without a capability until the owner saves recovery again. The app replaces a version 1 packet automatically the first time it is used for a restore.

7. Configure your own installation.

Run a compatible service behind HTTPS with PostgreSQL, atomic migrations, least-privilege runtime access and encrypted backups/disks. The normal app flow uses PROFILE_REGISTRATION=open. Operators can choose closed, or token for legacy/admin clients, and set MAX_PROFILES (1–1,000,000; default 10,000). Standalone startup defaults to closed until registration is explicitly enabled. Limit creation rates and body sizes at ingress; enforce the total profile quota atomically across replicas. Open registration is public enrollment, not authentication-free access to existing profiles.

The app defaults to https://cloud.getvouchers.app; another installation can supply --dart-define=CLOUD_SERVICE_URL=https://your-service.example, or choose a service address before linking a profile. The app must never embed a service-wide registration secret. Existing profile bindings stay with their original service. This reference does not require our private server repository: implement the contracts above and verify against the public vectors.

Keep capability headers, request bodies, sharing secrets and recovery inputs out of logs. UUIDs, sizes, timestamps and IP addresses remain visible metadata, as do the number of grants per profile, their creation and end times, and whether a grant is single-device and redeemed. Use scoped controller/proxy credentials: hiding them in a recipient UI cannot stop someone controlling that device from extracting its decrypted credentials.