Environment and Key Rotation

The main benefit of managing keys in the Federation is that many products do not need separate config updates.

provider keys

Provider keys can be managed through Runtime env and saved into the Federation database:

await admin.env.upsert({
  key: "OPENAI_API_KEY",
  value: "sk_new",
});

After rotation, every service handler connected to this runtime reads the new value. Env values in the database take priority over .env.

Downcity's own keys

Downcity maintains two critical keys of its own:

• DOWNCITY_FEDERATION_ADMIN_SECRET_KEY
• DOWNCITY_FEDERATION_TOKEN_SIGNING_KEY

admin secret

DOWNCITY_FEDERATION_ADMIN_SECRET_KEY is used by Admin City to manage Federation.

token signing key

DOWNCITY_FEDERATION_TOKEN_SIGNING_KEY is used internally by Federation to issue and validate user_token.

What to watch during rotation

• Rotating a provider key usually does not affect existing user_token
• Rotating DOWNCITY_FEDERATION_TOKEN_SIGNING_KEY invalidates old tokens
• If you rotate the signing key in production, shorten token TTL ahead of time or schedule a clear cutover window

Recommendations

• assign an internal owner for every provider key
• record key rotation time
• put production key rotation in a trusted backend or ops workflow instead of relying on manual browser actions