Rotation SOP — Alpaca Paper Trading API Keys

Mode: operator-assisted Last validated: 2026-04-24 UTC Validation method: read-only-docs (sandbox-rotation safe — paper account has no real-money impact) Average duration: 5m Required role: ops

Applies to: ALPACA_PAPER_API_KEY_ID, ALPACA_PAPER_API_SECRET_KEY (and any per-environment paper keys, e.g., dev/staging variants).

Important gotcha surfaced during research: Alpaca's "Reset Paper Account" button on the dashboard also regenerates the API key/secret. If an operator clicks "Reset" intending to clear simulated balance, they will silently invalidate the running paper credentials. The community has requested this behavior change for years; it is unresolved as of 2026-04-24. Always rotate via the explicit "Regenerate" / "View" path on the API Keys panel, never via the Reset button.

When to run

• Scheduled rotation (cadence: every 180 days — paper keys are lower risk than live)
• Operator-initiated (suspected compromise, off-cycle)
• After incident (employee offboarding)
• Any time the paper account is reset (even unintentional reset rotates the keys — treat as a forced rotation)

Prerequisites

• [ ] Alpaca dashboard access via SSO/email (operator)
• [ ] Confirm "Paper" environment is selected in the upper-left dashboard switcher (https://app.alpaca.markets/paper/dashboard/overview)
• [ ] Existing key in Infisical with history
• [ ] Downstream consumer list: Raptor backend (paper trading runtime), backtest service, any user-facing demo modes
• [ ] Paper account simulated balance and open orders snapshot (since rotation may coincide with a reset)

Steps

1. Pre-rotation checks

# Confirm current key still works against the paper endpoint
curl -sS -H "APCA-API-KEY-ID: $CURRENT_KEY_ID" \
     -H "APCA-API-SECRET-KEY: $CURRENT_SECRET" \
     https://paper-api.alpaca.markets/v2/account | jq '.status'
# Expect: "ACTIVE"

Snapshot any open paper orders/positions in case a downstream restart cancels them.

2. Generate the new credential

There is no Alpaca API to rotate keys programmatically. The dashboard is the only path.

1. Navigate to https://app.alpaca.markets/paper/dashboard/overview.
2. Confirm the environment switcher (upper-left) shows Paper Trading.
3. In the right sidebar, locate the API Keys section.
4. Click "View" on the existing key OR "Regenerate" if the dashboard offers it (UI varies by account vintage).
5. If only "Generate New Keys" is available, that creates a fresh pair and invalidates the old keys atomically.
6. Copy both Key ID and Secret Key immediately. The Secret is shown once.

3. Validate the new credential

NEW_KEY_ID="..."
NEW_SECRET="..."
curl -sS -H "APCA-API-KEY-ID: $NEW_KEY_ID" \
     -H "APCA-API-SECRET-KEY: $NEW_SECRET" \
     https://paper-api.alpaca.markets/v2/account | jq '{status, account_number, buying_power}'
# Expect: status = "ACTIVE", account_number unchanged from pre-rotation snapshot.

4. Store in Infisical

infisical secrets set ALPACA_PAPER_API_KEY_ID="$NEW_KEY_ID" \
  --projectId="$INFISICAL_PROJECT_ID" --env=prod
infisical secrets set ALPACA_PAPER_API_SECRET_KEY="$NEW_SECRET" \
  --projectId="$INFISICAL_PROJECT_ID" --env=prod

5. Propagate to downstream consumers

6. Verify downstream

# Hit the Raptor endpoint that proxies Alpaca paper /v2/account
curl -sS https://api.raxx.app/api/trading/account | jq '.alpaca_status'
# Expect: "ACTIVE" (or whatever wrapper the Raptor route emits on success)

Place a paper test order via the Raptor API and verify it appears in the Alpaca paper dashboard:

curl -sS -X POST https://api.raxx.app/api/trading/orders \
  -H "Content-Type: application/json" \
  -d '{"symbol":"AAPL","qty":1,"side":"buy","type":"market","time_in_force":"day","mode":"paper"}'
# Confirm order ID appears in https://app.alpaca.markets/paper/dashboard/orders

7. Revoke the old credential

The Alpaca dashboard's "Generate New Keys" / "Regenerate" action already invalidates the old key pair atomically — no separate revoke step is needed. Confirm:

curl -sS -o /dev/null -w "%{http_code}\n" \
     -H "APCA-API-KEY-ID: $OLD_KEY_ID" \
     -H "APCA-API-SECRET-KEY: $OLD_SECRET" \
     https://paper-api.alpaca.markets/v2/account
# Expect: 401 or 403

8. Audit log entry

action: secret.rotate.completed
actor: <admin_id>
context: {"secret_name": "ALPACA_PAPER_API_KEY_ID", "method": "operator-assisted-dashboard", "rotated_at": "..."}

Rollback

No rollback exists. Once "Generate New Keys" is clicked the old keys are dead. Options:

1. If the new keys are broken or unusable, regenerate again (each click invalidates the previous attempt).
2. If propagation breaks downstream, revert the Heroku config vars to the previous value from Infisical history — but those will not authenticate against Alpaca. The only correct fix is to redo step 5+6 with the current live keys.

Vendor doc references

• Paper trading: https://docs.alpaca.markets/docs/paper-trading
• API key creation guide: https://alpaca.markets/learn/connect-to-alpaca-api
• Paper trading start guide: https://alpaca.markets/learn/start-paper-trading
• Forum: paper key rotation behavior: https://forum.alpaca.markets/t/paper-trading-api-key-changes-with-reset/939

Known gotchas

• "Reset Paper Account" rotates keys as a side effect. Avoid clicking Reset unless you intended both the balance reset and the key rotation. There is no separation of concerns in the dashboard.
• Paper account number is stable across rotations. Use this as a sanity check in step 3.
• Secret is shown once; Key ID is always visible. Recopy carefully.
• No programmatic rotation API as of 2026-04-24. Multiple years of community requests have not produced a feature. Treat as permanently manual.
• Different keys for paper vs live. The paper dashboard switcher must be on "Paper" before clicking Generate. Cross-environment confusion is the single most common source of rotation incidents.
• Test orders during validation are real on the paper book. They will be filled / canceled per market hours. Use small qty and post-validation cancel.