Cloud Sync User Guide
Document version: 20260811
App versions supported by this document:
- iOS: >= 3.14
- Android: >= 1.4.0
- macOS / Windows (desktop): >= 1.0.14
Cloud Sync lets you sync rule-based configuration across Windows, macOS, Android, and iOS when signed in to the same account—no manual export/import or copy-paste between devices.
Important: Cloud Sync syncs rules and configuration files only. It does not upload your captured traffic. Capture data always stays on your device.
1. What Gets Synced
Cloud Sync currently supports 6 configuration types. Choose what to sync under Settings → Cloud Sync → Sync items:
| Sync type | Description |
|---|---|
| Host allow/block list | Host filtering rules for capture |
| DNS mapping | Rules that resolve domains to custom IPs |
| Rewrite rules | Mock, rewrite, drop, redirect, etc. |
| Scripts | User-written JavaScript scripts |
| Combo replay | Combo replay workflow rules |
| Protobuf descriptor files | .desc and similar files for Protobuf decoding |
Not synced:
- Capture history, sessions, request/response bodies, or other traffic data
- Certificates, favorited requests, favorited API docs, etc.
- Your encryption passphrase (see "End-to-End Encryption" below)
2. How to Use
2.1 Prerequisites
- Sign in to your ApiCatcher account (email + verification code)
- Your account has Cloud Sync access
- Set an encryption passphrase under Settings → Cloud Sync (see Section 4)
- Turn on Enable Cloud Sync
2.2 First-time setup on a device
- Open Settings → Cloud Sync
- Read the end-to-end encryption notice on the page
- Set and confirm your encryption passphrase, then save
- Enable Cloud Sync
- Select configuration types to sync
- Optionally tap Sync Now for an immediate sync
2.3 Setting up a new device (cloud data already exists)
- Sign in to the same account
- Open Cloud Sync and enter the same passphrase as your first device
- Save the passphrase and enable Cloud Sync
- Tap Sync Now to pull and decrypt configuration from the cloud
If the passphrase is wrong, the app will warn about a mismatch or failed decryption—double-check it matches what you set originally.
2.4 Day-to-day use
- After you edit synced configuration (Host rules, DNS mapping, rewrite rules, etc.), the app waits briefly (~2 seconds) then uploads changes automatically—usually no manual action needed.
- When you open the app or return to the foreground, it checks for cloud updates and pulls them.
- Opening a rule list page also pulls the latest cloud data for that rule type.
- You can tap Sync Now anytime for a manual sync.
2.5 Delete cloud data
At the bottom of Cloud Sync settings, use Delete Cloud Data.
- Removes encrypted backups on the server only—local configuration on your device is kept.
- If you forget your passphrase or need a new one, you typically delete cloud data first (see Section 5).
3. How Incremental Sync Works
Cloud Sync uses incremental sync—it does not re-upload your entire configuration every time. Here is a plain-language overview.
3.1 Only changes are uploaded
When you add, edit, or delete a rule in a synced category, the app marks that item as pending sync. After a short delay, only changed items are encrypted and uploaded—not the full library.
3.2 A change list in the cloud
Each configuration type has a version number and an item list (ID, update time, deleted flag). During sync:
- Your device asks the cloud: "What version is this type at? Which items changed?"
- It compares with local state and downloads only new cloud changes missing locally
- It pushes local pending changes to the cloud
So if you have hundreds of rewrite rules but edit one, usually only that one syncs.
3.3 Two devices edit the same item
If two devices nearly simultaneously edit the same item, the cloud keeps the copy with the newer update time (last write wins). This keeps all devices converging instead of blocking sync.
Tip: avoid editing the same rule on multiple devices at once; if conflict occurs, the last saved/synced version wins.
3.4 Capture traffic is never synced
This process applies to rules and configuration only. Request lists, response bodies, and other capture data never enter Cloud Sync and are never uploaded to ApiCatcher servers.
4. End-to-End Encryption (E2EE)
Cloud Sync uses end-to-end encryption. In short: only you (and devices using the same passphrase) can read your configuration; under normal operation, our servers and ApiCatcher cannot read plaintext.
4.1 Encryption happens on your device
When you save synced configuration:
- You enter an encryption passphrase on your device
- The app derives an encryption key locally (the key is never uploaded)
- Configuration is encrypted and compressed on your device before upload
- The server receives ciphertext—data that cannot be read directly
The server stores ciphertext only—not readable Host rules, script source, etc.
4.2 Your passphrase stays on your device
- The passphrase is never uploaded to ApiCatcher servers
- It is stored in secure local storage (e.g., iOS Keychain, Android encrypted storage, desktop secure storage)
- When you sign out, the encryption passphrase stored on this device is cleared automatically
ApiCatcher does not know or store your passphrase. We cannot "recover" it for you.
4.3 What's on the server? Is my passphrase stored?
No. Encryption-related server data is mainly:
| Stored item | Purpose | Can it recover passphrase or plaintext? |
|---|---|---|
| Encrypted configuration (ciphertext) | Backup of your rules | No—without passphrase/key, cannot decrypt |
| Key fingerprint | Verify all devices use the same encryption key | No—hash of the key, cannot reverse to passphrase |
| Salt | Public input for passphrase-based key derivation | No—salt alone cannot decrypt |
In simple terms:
- Passphrase → used only on your device, never uploaded
- Key → derived on device from passphrase, never uploaded
- Key fingerprint → a "checksum" of the key uploaded for verification—not the passphrase itself
4.4 How does a new device verify my passphrase?
A common question: "If the server doesn't know my passphrase, how does my new phone know I typed it correctly?"
The flow:
- On your first device, when you set a passphrase and enable Cloud Sync, the app derives a key and computes its fingerprint, then registers that fingerprint with the cloud (linked to your account).
- On a new device, after sign-in, the app fetches salt and the registered fingerprint from the cloud—still no passphrase.
- You enter your passphrase; the app derives the key locally with the same algorithm and computes a fingerprint.
- If the local fingerprint matches the cloud fingerprint, the passphrase is correct—you can decrypt and sync.
- If it does not match, the passphrase is wrong or differs from your first device; uploads are blocked and downloaded ciphertext cannot be decrypted.
Verification happens locally on your new device. The cloud only provides a fingerprint to compare against—it never receives your passphrase.
4.5 All devices must use the same passphrase
Every syncing device needs the same encryption passphrase so keys and fingerprints match. A different passphrase triggers mismatch warnings and prevents syncing with existing cloud data.
4.6 Security tips
- Use a strong passphrase and store it safely.
- Do not share your passphrase with untrusted parties—anyone with it could decrypt your cloud configuration on their device.
- ApiCatcher will never ask for your encryption passphrase.
5. Forgot Your Encryption Passphrase?
With end-to-end encryption, a forgotten passphrase cannot be recovered through ApiCatcher or our servers—we never store it, and there is no "reset passphrase and keep old data" backdoor.
5.1 Why can't I just change the passphrase and keep old data?
Cloud data was encrypted with a key derived from your old passphrase. Without it, your device cannot derive the correct decryption key—the ciphertext stays unreadable. This is intentional security design: even if server data leaks, content stays protected without the passphrase.
5.2 What to do
If you cannot recover your passphrase:
- On a device with Cloud Sync enabled, open Cloud Sync
- Choose Change Passphrase. This clears encrypted data stored in the cloud and the key fingerprint
- Because this action clears both the local encryption passphrase and cloud data, repeat Change Passphrase on each other device that has Cloud Sync enabled
- After Change Passphrase has been completed on every device, set a new encryption passphrase on each device one by one and enable Cloud Sync. Once Cloud Sync is enabled again, the current local configuration on each device uploads and forms a new cloud backup
5.3 Recommendations
- Store your passphrase in a trusted password manager.
- Before changing the passphrase, ensure at least one device still has a local copy of your configuration.
6. FAQ
Q1: Is Cloud Sync the same as real-time sync to Burp Suite / desktop?
No. Cloud Sync syncs rules and configuration. Real-time sync (e.g., to Burp Suite or a WebSocket receiver) syncs captured traffic—a separate feature.
Q2: Can I use Cloud Sync without signing in?
No. Cloud Sync links encrypted backups to your account and verifies access permissions.
Q3: If I turn off Cloud Sync, is cloud data deleted?
No. Turning off sync stops further syncing but does not auto-delete existing cloud backups. Use Delete Cloud Data to remove server copies.
Q4: Does uninstalling delete cloud data?
No. Uninstall affects only the local device. Remove cloud backups via Delete Cloud Data in the app or account deletion flow.
Q5: What happens when my session expires?
Cloud Sync turns off automatically. Sign in again and re-enable it.
7. Related Links
- Privacy Policy — includes Cloud Sync data handling
- Terms of Service — includes Cloud Sync usage terms
Questions: [email protected]