Browse this guideRotate credentials
DevelopmentUpdated 2026-11-04

Rotate credentials

Rotate a credential when it may have been exposed, when someone who held it leaves, or before it expires. Each one below says where it lives, what to do, and what a service that keeps the old value will do. Always set the new value everywhere it lives before you retire the old one, unless a step says the old one must stop working first.

Never paste a credential into a page, a ticket, a commit, or a pull request. Put it only in the setting this page names.

CredentialLives inNeeds a redeploy
Deposit identity passwordsRailway SITE_DEPOSIT_AUTH_PASSWORD, one per serviceThat service
site_ingress database passwordRailway ingress SITE_DATABASE_URLingress
Worker database passwordRailway worker SITE_DATABASE_URLworker
Twilio auth tokenRailway ingress TWILIO_AUTH_TOKENSingress
Twilio media API keyRailway worker TWILIO_API_KEY_SID and TWILIO_API_KEY_SECRETworker
Anthropic API keyRailway worker ANTHROPIC_API_KEYworker
Container registry credentialRegistry setting of every Railway service the Site runs (ingress, worker, and mcp when the Site runs it)Each, on its next deploy
Railway project tokenGitHub Environment secret RAILWAY_PROJECT_TOKENNothing; used by the next deploy
Vercel tokenGitHub Environment secret VERCEL_TOKENNothing; used by the next deploy
Service-role keyOperator's shell, for one runNothing; no service holds it

A Site that runs the mcp service holds no secret there: it forwards each caller's own token, so rotating a secret never touches it. Only the registry credential and the Supabase publishable key do.

Deposit identities

The ingress and worker services each sign in to Supabase Auth as their own Deposit user. Ingress may only add to the Deposit; the worker may add and read.

  1. Rotate one identity from site/db, with the service-role key set for this run only:

    $env:SUPABASE_URL = "https://<project-ref>.supabase.co"
    $env:SUPABASE_SERVICE_ROLE_KEY = "<service-role key>"
    uv run python scripts/provision_deposit_identities.py --rotate ingress
    

    Use --rotate worker for the worker. The script sets a new password, prints it once, and signs that user out everywhere by revoking every refresh token it has.

    • Check: it prints one <email> <password> line and exits 0.
  2. Set the new password in that service's SITE_DEPOSIT_AUTH_PASSWORD on Railway, and redeploy that service.

    • Check: for ingress, /health reports deposit_auth: ok. For the worker, it stays up and a test text reaches captured.

What happens if you skip step 2. The old password is refused the next time the service has to sign in. A worker that meets the refused credential during Capture or Extract logs one error and exits, releasing the row it held without processing it and without failing it. Railway shows the worker as crashed once its restart limit is used up, and rows stay received or captured until you update the variable and redeploy. An ingress that is refused when it signs in reports deposit_auth: error on /health and returns 503, so Twilio retries rather than losing the message.

What stays valid. An access token already issued stays valid until it expires, up to an hour by default, even after the sign-out. Rotation is not an instant cutoff for a token already in someone's hands.

Script: provision_deposit_identities.py.

Database passwords

  1. site_ingress. Set a new password for the role in the Supabase SQL editor, then update the password in ingress's SITE_DATABASE_URL, percent-encoded, through the session pooler, and redeploy ingress.
    • Check: /health reports db: ok.
    • What happens in the gap. Between the change and the redeploy, ingress cannot insert and returns an error that Twilio retries. Do the two steps back to back.
  2. The worker's role. Change the password in the Supabase project's database settings, then update the worker's SITE_DATABASE_URL, and redeploy worker. Any operator connection string that uses the same role needs the same update.
    • Check: the worker stays up and processes a test text.

Twilio

  1. Auth token (ingress uses it to check webhook signatures). TWILIO_AUTH_TOKENS takes a comma-separated list so the old and new tokens overlap. Add the new token beside the old one, redeploy ingress, change the token in Twilio, then remove the old one and redeploy again.
    • Check: after each redeploy a test text produces intake_inserted. A signature_rejected line means ingress does not hold the token Twilio is signing with.
  2. Media API key (the worker uses it to fetch attachments). Create a new media-read-only key, set TWILIO_API_KEY_SID and TWILIO_API_KEY_SECRET on the worker, redeploy worker, then delete the old key in Twilio.
    • Check: a test text with a photo reaches captured with its attachment.

Anthropic API key

Create a new key with its own monthly spend limit, set ANTHROPIC_API_KEY on the worker, redeploy worker, then revoke the old key.

Container registry credential

The registry credential is a classic personal access token with only read:packages, set on every Railway service the Site runs (ingress, worker, and mcp when the Site runs it) so they can pull the private image. It expires.

  1. Renew it before it expires. Create the new token, set it on each of those services, then revoke the old one.
    • Check: the next Deploy run passes its wait step. An expired credential shows up as a failed wait step on the next deploy, not before it, so a calendar reminder is the only early warning.

Deploy tokens

The Railway project token and the Vercel token live only as secrets in the Site's GitHub Environment site-<site>.

  1. Create the new token on the platform, scoped as before: the Railway token to the one environment.
  2. Replace the secret in the GitHub Environment, then delete the old token on the platform.
    • Check: dispatch the matching workflow from main and see it authenticate.

Credentials no service holds

The Supabase service-role key is an operator credential. The provisioning scripts read it from the shell for one run, and neither backend process nor the web app receives it. If it may have been exposed, rotate it in Supabase; no deployed service needs updating. The Supabase publishable key is designed to appear in browser code. If it changes, update SITE_SUPABASE_PUBLISHABLE_KEY on each Railway service the Site runs (ingress, worker, and mcp when the Site runs it) and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY in the GitHub Environment, then redeploy each of those services and the web app, since the web build inlines it.