Key Rotation

Starting in SDK v2.1.0, you can rotate tokens without pushing an app store update. The trick: use a stable App ID instead of embedding tokens directly in your binary.

SDK v2.3.0+

SwiftPatch uses separate App Tokens (at_ prefix) for the SDK and Deployment Keys (dk_ prefix) for CLI/CI. Each can be rotated independently.

The Problem

Before v2.1.0, the deployment key was hardcoded in native config. Regenerating it meant every existing install stopped receiving updates until users downloaded a new binary from the app store.

The Solution: App ID

The App ID is a stable identifier that never changes. When the SDK uses an App ID, it:

1. Resolves the current app token from the server on first launch
2. Caches the token on device
3. Automatically refreshes the token if it becomes invalid after rotation

You can regenerate your app token at any time, and all installs pick up the new token on their next check.

Step 1: Upgrade to SDK v2.1.0+

npm install @swiftpatch/react-native@latest
cd ios && pod install && cd ..

Step 2: Replace Deployment Key with App ID

Find your App ID in the dashboard under Settings.

iOS -- Info.plist:

<!-- Remove legacy keys -->
<!-- <key>SwiftPatchAppToken</key> -->
<!-- <string>at_YOUR_APP_TOKEN_HERE</string> -->

<!-- Add App ID -->
<key>SwiftPatchAppId</key>
<string>YOUR_APP_ID</string>

Android -- strings.xml:

<!-- Remove legacy keys -->
<!-- <string name="SwiftPatchAppToken">at_YOUR_APP_TOKEN_HERE</string> -->

<!-- Add App ID -->
<string name="SwiftPatchAppId">YOUR_APP_ID</string>

Step 3: Push an App Store Update

This is the last app store update needed for credential changes. After this, rotations are handled automatically.

Step 4: Rotate Tokens

Step 1: Go to your app's Tokens page in the dashboard.

Step 2: Click Regenerate next to App Token or Deployment Key.

Step 3: Confirm.

All installs pick up the new token within minutes.

tip

You can rotate the App Token and Deployment Key independently. Rotating one does not affect the other.

How It Works

App Launch -> SDK checks for app token
  |-- Has deploymentKey in native config? -> Use directly (legacy)
  +-- Has appId? -> Resolve from server (v2.3.0+)
          +-- POST /sdk/resolve-key -> returns { appToken, deploymentKey }
              +-- SDK caches token -> normal update flow

On token rotation:

SDK uses cached (old) token -> Server responds INVALID_DEPLOYMENT_KEY
  -> SDK clears cache -> resolves new token via appId
  -> caches new token -> retries update check

Token Types

Token	Prefix	Purpose	Rotated via
App Token	at_	SDK runtime (check/download updates)	Dashboard > Tokens
Deployment Key	dk_	CLI/CI automation	Dashboard > Tokens
App ID	(none)	Stable identifier, never changes	Cannot be rotated

Security

• App ID identifies your app but does not grant access alone
• The resolve-key endpoint is rate-limited
• App tokens grant read-only SDK access only
• Setting bundleIdentifier in the dashboard adds an extra layer of security

Backward Compatibility

• Apps using SwiftPatchDeploymentKey or SwiftPatchAppToken continue to work
• The server accepts both at_ and dk_ tokens in API calls
• You can migrate gradually -- all methods work simultaneously

FAQ

What if the device is offline when the token is rotated?

The app uses the cached token. When it is rejected, the SDK resolves the new one. If still offline, updates pause until connectivity returns. The app itself keeps running.

What is the difference between App Token and Deployment Key?

App Token (at_) is for the mobile SDK. Deployment Key (dk_) is for CLI/CI. They are separate and rotate independently.

Can I switch back to a hardcoded deployment key?

Yes. Add SwiftPatchDeploymentKey to native config and the SDK uses it directly.