Secret Rotation
Rotate credentials by storing a replacement value, then roll services forward to the new version. Provider-side key creation and old-key revocation stay in your automation today.
Current rotation model
Agent Secret Store stores the replacement value and records the new version. It does not currently create provider keys, run built-in cron schedules, maintain grace-period dual reads, or expose rollback APIs. Use your scheduler or CI/CD job to create the provider credential, write it to the vault, smoke test it, then revoke the old provider key.
Manual rotation
Use the dashboard for human-controlled rotation, the CLI for operator workflows, or the SDK when an internal service is allowed to write the replacement value.
CLI
# User-authenticated CLI rotation
ass secrets rotate production/gemini/GEMINI_API_KEY \
--value "$NEW_GEMINI_API_KEY"
# Or store a new version through the normal write path
ass secrets set production/gemini/GEMINI_API_KEY "$NEW_GEMINI_API_KEY" \
--type api_key \
--tier sensitivePython SDK
import os
from agentsecretstore import AgentVault
async def store_replacement_gemini_key(new_key: str) -> None:
async with AgentVault(agent_key=os.environ["ASS_AGENT_KEY"]) as vault:
updated = await vault.set_secret(
"production/gemini/GEMINI_API_KEY",
new_key,
secret_type="api_key",
access_tier="sensitive",
metadata={"rotated_by": "scheduled-job"},
)
print(f"Stored version {updated.version}")REST
# User-authenticated REST rotation endpoint
curl -X POST \
https://api.agentsecretstore.com/v1/secrets/production/gemini/GEMINI_API_KEY/rotate \
-H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
-H "Content-Type: application/json" \
-d '{"new_value": "'"$NEW_GEMINI_API_KEY"'"}'Scheduled rotation
Run scheduled rotation in your own CI/CD or job scheduler. The job should create the new provider key, write it to the vault, run a smoke test, deploy or restart consumers if needed, and only then revoke the old provider key.
# .github/workflows/rotate-gemini-key.yml
name: Rotate Gemini key
on:
schedule:
- cron: '0 2 * * 0'
workflow_dispatch:
jobs:
rotate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install Agent Secret Store SDK
run: python -m pip install agentsecretstore
- name: Generate and store replacement key
env:
ASS_AGENT_KEY: ${{ secrets.ASS_AGENT_KEY }}
run: |
NEW_GEMINI_API_KEY=$(./scripts/create-gemini-key.sh)
export NEW_GEMINI_API_KEY
python - <<'PY'
import asyncio
import os
from agentsecretstore import AgentVault
async def main() -> None:
async with AgentVault(agent_key=os.environ["ASS_AGENT_KEY"]) as vault:
await vault.set_secret(
"production/gemini/GEMINI_API_KEY",
os.environ["NEW_GEMINI_API_KEY"],
secret_type="api_key",
access_tier="sensitive",
metadata={"rotated_by": "github-actions"},
)
asyncio.run(main())
PYCache-safe rollout
Keep agent-side secret caches short-lived and provide an explicit invalidation hook. After rotation, restart long-running workers or call the invalidation hook before the next model request.
import os
from agentsecretstore import AgentVault
_cached_gemini_key: str | None = None
async def get_gemini_key() -> str:
global _cached_gemini_key
if _cached_gemini_key is None:
async with AgentVault(agent_key=os.environ["ASS_AGENT_KEY"]) as vault:
_cached_gemini_key = await vault.get_secret(
"production/gemini/GEMINI_API_KEY"
)
return _cached_gemini_key
def invalidate_secret_cache() -> None:
global _cached_gemini_key
_cached_gemini_key = NoneRecovery
If a replacement credential fails validation, rotate again with a known-good value. Keep the old provider key alive until the replacement passes smoke tests.
# If the replacement key is bad, rotate again with a known-good value.
ass secrets rotate production/gemini/GEMINI_API_KEY \
--value "$KNOWN_GOOD_GEMINI_API_KEY"
# Confirm the active value works before revoking the bad provider-side key.
ass secrets get production/gemini/GEMINI_API_KEY --silent | ./scripts/smoke-test-gemini.shRotation checklist
- 1
Create the replacement provider key
Generate the new Gemini or Bedrock credential in the provider console or automation job.
- 2
Write the replacement to the vault
Use the dashboard, CLI, SDK, or user-authenticated REST rotation endpoint.
- 3
Smoke test before revocation
Fetch the active vault value and run a provider API check before deleting the old key.
- 4
Refresh long-running agents
Restart workers or invalidate their local secret cache so the next request reads the new value.
- 5
Audit and document
Confirm the audit trail records the write or rotation event and attach the result to your runbook.
Vault Storage →
Learn about versioning, access tiers, and secret metadata.
Security Best Practices →
Recommended scoping and monitoring patterns.
Audit Trail →
Review rotation events and compliance exports.
Approval Workflows →
Require approval for sensitive or critical access.