Overview
Every Countly application has an app key that SDKs send with every request so Countly knows which application the data belongs to. Because the key is embedded in your apps (mobile builds, web pages, and server integrations), you may occasionally need to change it. Whether in response to an exposure or as part of routine security hygiene.
App Key Rotation lets you change an application's key without losing data, resetting users, or breaking already-deployed clients. When you set a new key, the old key continues to work as an expected key until you retire it.
Why It Matters
Previously, changing an app key effectively started a new application: in-field clients on the old key stopped being accepted, and returning users were recorded as new. Rotation removes that penalty entirely.
What happens when you rotate a key
When you set a new app key, Countly does not discard the old one. Instead:
- The new key becomes the current key. New SDK setups should use it.
- The old key is kept as an accepted key and continues to work. Data sent with it is still accepted and attributed to the same application.
- Users and historical data are unaffected. Visitors are recognized as the same users regardless of which key their app uses. No duplicate users, no reset of returning/new counts.
This means you can gradually roll out a new key. Updated clients use the new key; older clients that you cannot update immediately (e.g., mobile versions still in the field) continue working on the old key until they upgrade or naturally fall out of use. You decide when an old key has been idle long enough to retire it safely.
Rotating the App Key
All key management lives in one place in Countly. Follow the steps below to rotate an app key using the dashboard.
- Go to Management > Applications and select the application whose key you want to rotate.
- Click Edit on App Information, change the App Key field, and click on Save.
- A confirmation dialog "Change the App key" appears, explaining that the old key stays accepted and existing users are preserved.
- Confirm to apply the change.
Key Uniqueness Requirement
The new key must be unique across all applications in your Countly instance, including keys that are still accepted from previous rotations. Choosing a value already in use (current or accepted by any app) is rejected.
The new key takes effect immediately. The previous key is automatically moved to the Accepted app keys list and continues to work.
Updating Your SDK Configurations
After rotation, update your SDK configuration and server integrations to use the new key wherever you can. The new key takes effect immediately, and the previous key remains accepted.
Monitoring Accepted Keys
Below the App Information section, the Accepted app keys section lists every key the application currently accepts. Use this view to track whether an old key is still receiving data from clients in the field.
Each entry in the Accepted app keys table shows the following columns:
| Column | Description |
|---|---|
| App key | The key value. The active key is tagged Current. |
| Last received data | The timestamp of the most recent request received using this key. |
The Last received data timestamp advances as data arrives, so a key that has been quiet for a while is a good candidate for retirement.
Retiring an Old Key
Once you are confident that an old key is no longer in use, or you want to immediately invalidate a compromised key, you can retire it. Retiring a key removes it from the accepted list and causes Countly to reject any subsequent requests that use it.
Retirement Is Immediate and Irreversible
Once retired, requests using that key are rejected as if the application does not exist.
Steps to Retire a Key
- In the Accepted app keys section, locate the key you want to retire.
- Click Retire next to that key.
- Confirm in the "Retire app key" dialog. The key is removed from the accepted list immediately.
Current Key Cannot Be Retired
The Retire action is hidden on the current key. An application always retains at least one accepted key, so you must first rotate to a new key before the previous one becomes retirable.
Propagating Timing
Rotations and retirements are read through a short-lived internal cache. A newly rotated key works right away; a retired key can take up to about a minute to stop being accepted everywhere. In practice, you retire keys that are already idle, so this is not noticeable.
Using the API
The same operations available in the dashboard are also accessible through the apps management API. This is useful for automation pipelines or builds where the dashboard screens are not yet present.
| Operation | Request |
|---|---|
| Rotate the key | POST /i/apps/update with args.key = "<newKey>" |
| Retire an old key | POST /i/apps/update with args.remove_keys = ["<oldKey>"] |
| List all accepted keys | GET /o/apps/all or /o/apps/mine, each app returns a keys array |
Keys Array Shape
Each entry in the keys array returned by the listing endpoints has the following shape:
{
"key": "<value>",
"added_at": <unix_seconds>,
"last_data": <unix_seconds>
}The last_data field is the Unix timestamp (in seconds) of the last time data was received for that key. A value of 0 means no data has been received yet. Note that the current key cannot be removed via remove_keys. This is enforced server-side.
Recommended Rotation Approach
For a smooth, zero-disruption key rotation, follow this sequence:
- Set the new key and begin using it in new deployments and integrations.
- Roll the new key out to your existing clients and integrations over time.
- Monitor the Last received data timestamp on the old key in the Accepted app keys section.
- Once the old key has been quiet long enough for your situation, retire it.
No Fixed Deadline
There is no enforced expiry on accepted keys. An old key can stay accepted as long as you need. Retire it whenever you decide it is safe to do so.
Verifying the Rotation
After rotating, confirm the following to ensure everything is working as expected:
- The Accepted app keys section shows the new key tagged as Current and the old key in the list below it.
- Data sent by clients using the new key appears in Countly as expected, attributed to the correct application.
- Data sent by clients still using the old key continues to be accepted and attributed to the same application; no new sessions or duplicate users should appear.
- The Last received data timestamp on the old key continues to advance if any in-field clients are still sending data with it.
Upgrade Behavior
If you are upgrading an existing Countly Server deployment to a version that includes App Key Rotation, no migration script is required. The following applies automatically:
- Existing applications keep working unchanged. Incoming requests continue to resolve against the application's current key.
- Existing users retain their identity (IDs are byte-identical); user IDs are unchanged, so there is no reset of user history.
- An application's Accepted app keys list is created the first time that the application is saved or rotated after the upgrade. Until then, the current key is shown as the single accepted key.