Credentials and access
Where every tool's key on a DevStride machine comes from, who creates and rotates it, how setup fetches the team's keys, and what a retired machine still holds.
On this page
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). Whose accounts the agents' keys belong to, and how each is proven live, is on Canary accounts.
Today's decision: shared keys with full access
To get everything working, the team's keys are shared and have full access (owner, 2026-10-05). The Seed token can deploy any stage, production included; the Neon key reaches staging and production; the GitHub, DevStride and Stripe keys are the same on every machine; and every enrolled agent machine has administrator access to both AWS accounts. Narrower access, per person or per machine, comes later.
How keys reach a machine#
- 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.
- 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.
ds secrets pullwrites 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.ds machine readyproves them. It checks that every checkout's.envholds 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#
| Tool | Its credential | Comes from | Created and rotated by |
|---|---|---|---|
| AWS, your own machine | your own AWS sign-in (IAM Identity Center): administrator access to the dev account, and for an admin the management and production accounts too | an admin creates it with ds team add-developer; setup writes a self-renewing sign-in and a profile for each account it reaches, then you sign in once in the browser |
you set its password; an admin grants and removes it (For admins) |
| AWS, an agent machine | the machine's own certificates, one per account | ./setup --agent <name>, from one approval |
setup; renewed yearly with ds machine enroll <name> --force then ./setup --agent <name>; shut off with ds machine revoke <name> |
| GitHub, agents | GH_TOKEN |
the agents' bundle | the owner |
| GitHub, you | your own GitHub account, signed in by the setup line (gh auth login) |
an admin invites it to devstride/devstride and devstride/ds-docs with ds team add-developer (an admin: to the devstride organisation as an owner, with --role admin); you accept |
you; an admin removes its access, organisation membership included, with ds team remove-developer |
| DevStride, you | your own sign-in to the DevStride workspace (https://app.devstride.com/devstride) | ds team add-developer invites your work email; you accept the email. An admin is made an Owner on the admin's next run of the command |
you; an admin removes the membership with ds team remove-developer |
| DevStride, agents | DEVSTRIDE_API_KEY, DEVSTRIDE_API_SECRET, DEVSTRIDE_ORG_ID, DEVSTRIDE_ORG_SLUG |
the agents' bundle; setup connects Claude Code and Codex to DevStride with them. If you signed in to DevStride in Codex yourself, setup keeps your sign-in | the owner |
| Stripe | STRIPE_INVENTORY_KEY (restricted, read-only), and the test-mode keys |
the agents' bundle; the shared bundle | the owner |
| Seed (our deploy service) | SEED_TOKEN |
the agents' bundle | the owner, in Seed's organisation settings |
| Neon (our Postgres host) | NEON_API_KEY, the organisation key |
the agents' bundle | the owner, in Neon's organisation settings |
| QuickBooks | the agents' QuickBooks app keys and refresh tokens (sandbox and real) | the agents' bundle | a person grants each company (Granting QuickBooks again); when a token is used Intuit may hand back a new one, which ds quickbooks writes back for you |
| Microsoft Graph | the agents' Entra app (tenant, client, secret) | the agents' bundle | ds graph rotate-secret makes a new secret, proves it, stores it, then ds graph retire-secret drops the old one |
| Claude Code | your claude.ai sign-in | you, when setup asks | you; never shared |
| Codex | your ChatGPT sign-in (or an OpenAI API key) | you, when setup asks | you; never shared |
| Sites only a browser reaches: the Seed and Neon consoles, Stripe, Intuit, Azure, the DevStride app | a one-time sign-in in each agent machine's DevStride Canary Chrome profile (see Canary accounts) |
a person, once per machine | that person |
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.
Your AWS profiles#
Setup writes a self-renewing sign-in session ([sso-session devstride] in ~/.aws/config) and one profile for each AWS account your sign-in reaches. One browser sign-in serves them all; the session renews itself until IAM Identity Center ends it. A developer's sign-in reaches the dev account only, so a developer has the first row and nothing about the other two. If you already had a profile for an account under another name, setup keeps it, ds machine ready proves it, and setup tells you which variable to set (DEVSTRIDE_MGMT_PROFILE or DEVSTRIDE_PROD_PROFILE) so the commands use it too.
| Profile | Account | Who has it | What reads it |
|---|---|---|---|
devstride-dev (or the profile you already had for the account) |
dev (809603945909) | everyone | the ds wrapper, ds secrets pull, your machine's stage, ds machine ready. DEVSTRIDE_DEV_PROFILE names another |
devstride-mgmt |
management (032309179398), where IAM Identity Center and the agent machines' certificate authority live | admins | ds team, ds machine sign, ds machine revoke. DEVSTRIDE_MGMT_PROFILE names another |
devstride-prod |
production (290560638399) | admins | ds machine revoke and provision (DEVSTRIDE_PROD_PROFILE names another, and setup then writes that name); the data-conversion decrypt finds the profile for the production account by itself; the release's production health check is pointed at it |
ds machine ready proves every profile it finds; a lapsed management or production sign-in is listed as your step, with the aws sso login --profile <profile> line to run, and does not make the machine NOT READY (a lapsed dev sign-in does). Setup never rewrites a profile you already have: a profile named devstride-mgmt or devstride-prod that points somewhere else is left alone and named with its fix.
Rotating a shared key#
- Make the new key at the provider.
- Store it:
pbpaste | ds secrets set agent <KEY>(orshared). - Run
ds secrets pullon every machine (ds fleet statuslists them). For the DevStride API key, first runds machine ready --quickthere 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, andds secrets pulldoes not change either. - For the DevStride API key, renew just the connections you noted:
ds agent mcp-config --replacefor 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 runds agent mcp-config --codex. A connection that signs in as you, or holds a key of your own, is yours: leave it. - 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