Rekey

Zero-downtime API key rotation for developers and agents, using a dual-key (overlap) flow.

CLI / MCP ──► Orchestrator ──► Provider Adapter  (create / verify / revoke)
                         └───► Destination Updaters (write only)

Dual-key flow

1. Create a new key — the old key stays valid
2. Verify it (pre-flight)
3. Update every destination
4. Verify again
5. Revoke the old key (or let it expire)

The old key is never revoked unless steps 1–4 succeed. If something fails before any destination is written, the new key is revoked. If it fails mid-update, nothing is revoked and the report lists which destinations already hold the new key.

Bootstrap Modes (How keys are acquired)

Rekey supports three bootstrap mechanisms to mint or rotate keys, all adhering to the exact same dual-key interface:

Choose the mode in rekey.yaml via provider.mode: api | cli | oauth.

OAuth Flow Example (GitHub)

When using mode: oauth:

1. Rekey initiates RFC 8628 Device Flow and presents a short user code:

   [OAuth] Complete authentication in your browser:
     URL:  https://github.com/login/device
     Code: WDWN-ABCD
   

2. Your browser opens automatically; confirm the device.
3. Rekey securely stores the refresh & access token in ~/.config/rekey/oauth_tokens.json (0600 permissions).
4. Rekey completes the dual-key flow: verifies /user, syncs destinations, and lets old tokens expire.

Install & run

pip install -e ".[mcp,dev]"
cp rekey.example.yaml rekey.yaml        # edit ids; no secrets in this file
export OPENAI_ADMIN_KEY=...             # credentials come from env vars only

rekey list
rekey rotate openai-prod                # dry run (default)
rekey rotate openai-prod --execute

MCP server

REKEY_CONFIG=./rekey.yaml rekey-mcp

Add to your MCP client config (e.g. mcp_config.json):

{
  "mcpServers": {
    "rekey": {
      "command": "/abs/path/to/rekey/.venv/bin/rekey-mcp",
      "env": { "REKEY_CONFIG": "/abs/path/to/rekey/rekey.yaml" }
    }
  }
}

Provider credentials (e.g. OPENAI_ADMIN_KEY) must be in the server's environment — never pass them through the agent. Works with MCP SDK 1.x (FastMCP) and 2.x (MCPServer).

Tools: list_targets, rotate_key(target, dry_run=True). Responses contain only masked values and fingerprints — agents never see a secret. Assisted mode is refused over MCP.

Destinations & Environment Targeting

Rekey supports pushing rotated keys to multiple destinations and environments simultaneously:

destinations:
  - type: env_file
    path: .env.production
    variable: OPENAI_API_KEY

  - type: github_actions
    owner: myorg
    repo: my-app
    secret_name: OPENAI_API_KEY
    environment: production          # targets GitHub Environment

  - type: vercel
    project: my-nextjs-app
    env_name: OPENAI_API_KEY
    targets: [production, preview]   # updates multiple Vercel environments

Layout

src/rekey/
  adapters/      base.py openai.py github.py stripe.py assisted.py
  destinations/  base.py env_file.py github_actions.py
  orchestrator/  rotator.py
  mcp/           server.py
  cli.py config.py state.py secrets.py runner.py
tests/

Tests

pytest