Best practices

Key storage

• Use a secret manager. AWS Secrets Manager, Doppler, Infisical, 1Password CLI — anything audited. Don’t paste the key into source files.
• Inject via environment. Most agents read AC_AGENT_KEY from the process environment. Set it at runtime, not at build time, so a leaked image doesn’t leak the key.
• Never commit secrets. Pre-commit hooks (gitleaks, trufflehog) catch keys in CI. We don’t scan public GitHub repos for leaked keys — that’s on you.
• Use per-environment keys. Production, staging, and local development should each have their own key with the minimum scopes they need.

Minimum scopes

Mint each key with only the scopes it actually needs. A research bot doing read-only analysis should never carry the propose scope. A drift-correction worker should have propose but not extra reads it doesn’t use.

Rotation cadence

• Every 90 days as a default. Set expiresInDays: 90 at mint time and let the server enforce it.
• Immediately if a key shows up where it shouldn’t (logs, screenshots, public repos, customer support tickets).
• On employee offboarding if the key belonged to a specific person’s development setup.

Zero-downtime rotation

1. Mint a new key in /agent with the same scopes.
2. Deploy the new key alongside the old. Most secret managers
   support both for a short window.
3. Flip agent runtime to read the new key.
4. Watch lastUsedAt on the old key — when it stops advancing
   (~10 minutes for most agents), revoke it.

Per-key policy as a defense

On top of scopes, attach a per-key policy so a leaked read+propose key can’t propose against the entire portfolio. Cap the dollar amount per day. Restrict to a specific asset list. Bound by time-of-day. See Per-key policy constraints.

Webhook secrets

• Verify every delivery. Use verifyWebhook from the SDK or roll the HMAC yourself. Never trust an unsigned POST to your webhook URL.
• Reject stale timestamps. Default tolerance is 5 minutes. Don’t widen it without a reason.
• Rotate by recreate. Delete the webhook and create a fresh one with a new secret. We don’t support rotating in-place.

Network controls

• HTTPS only. The API rejects plain HTTP. Webhook URLs may use either protocol — we recommend HTTPS.
• Egress allow-list. If your agent runs in a constrained environment, allow api.advisorscrypto.com:443 only.
• IP allowlisting for your webhook receiver is on the roadmap. Until it ships, validate the signature on every delivery and treat the URL as semi-public.

What to log on your side

• Never the plaintext key. Log the prefix (the keyPrefix field).
• Every call you make. Method, path, request id (we’ll surface in a future release), status code, and the checkedAt from the response. Useful for cross-correlating with our audit feed.
• Webhook delivery ids. The X-AC-Delivery-Id header is your dedupe key and the easiest correlation point if you need to ask us about a specific delivery.

If something goes wrong

• Revoke first, investigate second. Cheap and instant. The audit log persists even after revoke so you can still see what happened.
• Email security@advisorscrypto.com with the key prefix and a rough timeline. We can scope an audit query and see what the key touched.
• Don’t panic about “execution risk.” The policy layer never let the trade happen.