Credentials and access

On this page you learn where each key on your machine comes from. You do not need to fetch any of them by hand: setup does it. Read this page before you add, rotate or troubleshoot a key, or give a new machine its access. The repository keeps the same map, kept current, in its ds-credentials skill (.claude/skills/ds-credentials/SKILL.md).

How keys reach a machine

1. Your AWS identity comes first. The team's keys live in AWS Secrets Manager in the dev account, so a machine reads them with its AWS identity. On your own machine that is your own AWS sign-in, which setup sets up so it renews itself. On an agent machine it is the machine's own certificate, issued from one approval during setup.
2. The keys sit in three bundles (one secret each in Secrets Manager):
   • devstride/dev/agent-env/shared: the same on every machine;
   • devstride/dev/agent-env/machine/<machine>: one machine's own AWS stage (DEVSTRIDE_STAGE, NEON_BRANCH, the stage's database and its sign-in pool), written by setup's stage step when it builds the stage; it wins over the shared bundle on the same key. The local Docker app needs none of it;
   • devstride/dev/agent-env/agent-api-keys: the agents' own credentials.
3. ds secrets pull writes them. The shared and machine bundles go into every checkout's .env; the agents' bundle goes only into ~/.config/devstride/agent.env, never into a .env, so an ordinary command never carries the agents' keys. Setup runs the pull; run it again yourself after a key changes.
4. ds machine ready proves them. It checks that every checkout's .env holds the keys the bundles delivered, and that the agents' file holds the four DevStride keys.

To add or change a key, put the value on standard input, never on the command line (where other processes can see it):

pbpaste | ds secrets set <shared|machine|agent> <KEY>

Every machine gets it on its next ds secrets pull, and an agent machine's hourly check reports when the bundles hold something newer than its .env. When a key seems missing, see A credential is missing.

One row per tool

Seed

Seed deploys on merge: a merge into develop deploys the dev stage, and a merge into master deploys production. Deploying therefore needs no key on your machine. Whether a commit is live is read from GitHub's deployment records, which Seed writes, with the agents' GH_TOKEN. SEED_TOKEN is only for a deliberate redeploy of a chosen commit with ds seed deploy --stage <stage> --commit <sha>. That token can deploy any stage, production included, so use it on purpose. Seed's console (its logs, retries and each stage's settings) is reached in the browser.

Neon

ds neon <neonctl arguments> runs Neon's command-line tool with the team's NEON_API_KEY, never with a person's own Neon sign-in, and from a private folder of its own. Name the project on every command with --project-id; it refuses init, link, checkout and set-context, which would pin a project for every session on the machine. ds neon api <route> reaches any Neon API route. The key reaches staging and production.

Setup's stage step needs it too: each machine's AWS stage gets its own Neon database branch, made with this key. Until an admin has added the key (For admins), ds neon refuses and says how it is added, and setup lists the stage under Needs you. Everything else on the machine works without it. ds neon --help and ds neon --version run without the key.

Rotating a shared key

1. Make the new key at the provider.
2. Store it: pbpaste | ds secrets set agent <KEY> (or shared).
3. Run ds secrets pull on every machine (ds fleet status lists them). For the DevStride API key, first run ds machine ready --quick there and note which DevStride connections say they read DevStride "with the agent bundle's key": Claude Code and Codex each keep a copy of the key, and ds secrets pull does not change either.
4. For the DevStride API key, renew just the connections you noted: ds agent mcp-config --replace for Claude Code; for Codex, delete both DevStride sections from ~/.codex/config.toml, [mcp_servers.devstride] and [mcp_servers.devstride.http_headers] (the second holds the key, and while either is there the command keeps the existing entry), then run ds agent mcp-config --codex. A connection that signs in as you, or holds a key of your own, is yours: leave it.
5. Only then revoke the old key at the provider. Revoking first breaks every machine until it pulls.

A revoked machine still holds what it pulled

Every machine, a person's included, pulls the agents' bundle. ds machine revoke <name> stops an agent machine getting new AWS credentials (a session it already holds ends within an hour), so it can no longer pull anything. Every key it pulled before stays valid until that key is rotated. A person's machine has no certificate to revoke: removing that person's AWS sign-in (For admins) does the same. Retiring or losing any machine therefore also means rotating GH_TOKEN, the DevStride API key, STRIPE_INVENTORY_KEY, SEED_TOKEN, NEON_API_KEY, the QuickBooks refresh tokens and the Graph secret, plus any shared key you would not want a stranger to hold.

Next: Plan work