Answers from our docs and articlesesc to close
Try asking
Create an accountSign up

App secrets from 1Password with op:// references

Set an app's environment variable to an op:// reference and the secret stays in 1Password: how it's read, when, how rotation works, and what fails.

Key takeaways

  • On Apps, a team connects a 1Password service account once, and any environment variable's value can then be an op:// secret reference instead of the secret.
  • Every build reads each reference from 1Password again. A dev server waking uses what the last build or Sync now read, because 1Password limits how often a service account reads.
  • To rotate, change the secret in 1Password and press Sync now: development restarts with the new value and production gets it on its next deploy.
  • A reference that doesn't resolve fails the build with the variable's name and the reason, so the app never starts with op://… where its secret should be.

Most apps end up with the same secret in two places: the password manager the team uses, and the host's environment variables. Rotate one and you have to remember the other. On Apps, an environment variable can point at the secret in 1Password instead of holding a copy you paste in. This post covers how that works, when the secret is read, and what happens when the read fails.

Connect a service account

1Password reads from code through a service account, which comes with 1Password Teams and Business. Create one at 1password.com in a browser (Developer, then Service Account under Access Tokens) and give it read access to the vaults your apps use. Keep separate vaults for development and production if you want production's secrets out of development's reach.

Then paste its token on Settings → Integrations → 1Password. The token starts with ops_, and 1Password shows it only once. Only team owners and admins can connect one. Before saving, Inference Bureau signs in with the token and lists its vaults. A token 1Password refuses, or one that can't read any vault, is never saved. The connection belongs to the team, so every app on the team can use it.

Point a variable at a secret

In 1Password, open the field's menu and choose Copy Secret Reference. Paste that as the variable's value on Settings → Environment variables:

# development
STRIPE_SECRET_KEY=op://Acme Dev/Stripe/secret key
# production
STRIPE_SECRET_KEY=op://Acme Prod/Stripe/secret key

A reference is op://vault/item/field or op://vault/item/section/field. A value that starts with op:// but doesn't match that shape is refused when you save it, so a typo can't reach your code as the value. Your code reads process.env.STRIPE_SECRET_KEY and gets the secret, not the reference. As with any variable, production uses development's value unless it has its own. If both environments should read different vaults, give production its own reference.

A reference isn't a secret, so the dashboard shows it in full, even on a variable marked secret.

When references are read

References are read when an environment's variables are put together, not on every request:

  • A build asks 1Password for every reference again. A deploy to production is a build, so whatever the vault holds at deploy time is what production runs with until its next deploy.
  • A dev server waking uses what the last build or Sync now read for the same reference. It asks 1Password only for a reference that has no saved value yet, such as one you just changed. Dev servers sleep and wake often, and 1Password limits how often a service account can read.
  • Sync now, in the integration's drawer, asks again for every reference in every environment.

Rotating a secret

Change the secret in 1Password, then press Sync now. It tells you which variables changed. If development's changed, its dev server restarts with the new values. Production's changed values are marked as changed, the same as an edited variable, and take effect on production's next deploy. Production never picks up a new value between deploys.

What Inference Bureau stores

  • The service account token, encrypted for your team. The dashboard shows only its last four characters and the names of the vaults it reads.
  • The reference, encrypted like every variable value.
  • The last value each reference resolved to, encrypted, one per environment. This is what lets a dev server wake, and a build go ahead while 1Password is unreachable, without reading again. The secret still reaches the running app as an environment variable, as any secret has to.

1Password remains the source of truth, and every build and Sync now refreshes the saved values from it. Connecting and disconnecting the account is recorded in the team's audit log with the vault names. A sync records only the names of the variables that changed.

When a reference doesn't resolve

The build fails, or the dev server doesn't start, with the variable's name and the reason. A failed build leaves the version that's live in place. The reasons come from 1Password:

  • No vault the service account can read has that name. Either it's a typo, or the account hasn't been given access.
  • More than one vault, item or field has that name. Use its id in the reference instead.
  • The vault has no item by that name, or the item has no such field or section.
  • The team hasn't connected 1Password at all.

If 1Password itself can't be reached or is rate limiting the account, a reference with a saved value uses it and the build goes on. One with no saved value fails. If 1Password stops accepting the token because it was revoked or expired, connect the account again with a new token. Disconnecting removes the token, and the next build of any app that still holds references fails and names them.

Frequently asked questions

Does the app call 1Password at runtime?

No. References are read when an environment's variables are put together: at every build, on Sync now, and when a dev server wakes with a reference it hasn't read yet. The app's code just reads process.env.

Which 1Password plans work?

Any plan with service accounts, which come with 1Password Teams and Business. The service account needs read access to the vaults your references name.

How do I rotate a secret stored in 1Password?

Change it in 1Password and press Sync now on Settings → Integrations → 1Password. Development restarts with the new value; production gets it on its next deploy.

What if 1Password is down during a deploy?

References that resolved before use their last value and the build goes on. A reference that has never resolved fails the build, naming the variable.

One bill for your apps, your models and your reviews.

Host apps and functions next to your model traffic. Routing picks each turn's model by your quality floor, and Auditor reviews every pull request against your own rules.