API Key Rotation Best Practices

Rotating a key means replacing it with a new one and retiring the old. Done in the right order, it causes no downtime. Done in the wrong order, checkout breaks. UPCS keys, which start with upcs_, are managed in the partner panel, where you can create and disable them.

Planned rotation

1. Create a new key in the partner panel and add the same allowed origins it needs, plus any IP restriction your servers require.
2. Store it in your secret manager under a new name or version.
3. Deploy servers with the new key. Roll out gradually if you have several instances.
4. Verify that session creation and lookups succeed and that error rates stay normal; see monitoring and logging API usage.
5. Disable the old key only after no traffic uses it.
6. Remove it from configuration and documentation.

Remember that the hourly limit applies per key, so traffic splits between keys during the overlap.

Why the order matters

Disabling a key takes effect immediately: running embed sessions created with it stop working (the embed reports key_inactive through onError), while direct API calls and new session requests fail with a plain 401 and the message "Invalid or inactive API key". If you disable first and deploy second, visitors with open map pages hit errors. Pages should recover by fetching a new session; see handle onError and session_expired.

Emergency rotation

When a key leaks:

1. Disable it right away.
2. Create and deploy a replacement.
3. Review your logs for unusual use.
4. Find how it leaked and fix that; see securing your UPCS API key.

Accept a brief outage over continued exposure, and keep a fallback so checkout continues with a normal address while the map is unavailable.

Make rotation easy

• Read the key from one configuration location.
• Do not copy the key into many services; wrap UPCS calls in one internal component.
• Use separate keys for production, staging and development.
• Document who can create and disable keys.