Skip to main content

Get started with secret references

A secret reference URI includes the name of the vault, item, section, and field where a secret is stored in your 1Password account:

You can use secret references to securely load information saved in 1Password into environment variables, configuration files, and scripts without storing any secrets in plaintext. Secret references are dynamic – if you update an item in 1Password, the changes will automatically be reflected in your code.

To replace secret references with the secrets they refer to at runtime, use op read, op run, or op inject.

tip

We recommend using 1Password Service Accounts to follow the principle of least privilege. Service accounts support restricting 1Password CLI to specific vaults, so that processes in your authorized terminal session can only access items required for a given purpose.

Requirements​

Before you can use secret references to securely load your secrets, you'll need to:

  1. Sign up for 1Password.
  2. Install 1Password CLI.
  3. Save the secrets you want to reference in your 1Password account.

Step 1: Copy secret references​

To see the option to copy secret references in the 1Password desktop app, turn on the 1Password desktop app integration.

To copy secret references:

  1. Open and unlock the 1Password desktop app.
  2. Open the item where the secret you want to reference is stored.
  3. Click next to the field that contains the secret you want to reference, then click Copy Secret Reference.
An item in 1Password with the Copy Secret Reference option selected.An item in 1Password with the Copy Secret Reference option selected.

If the name of the vault, item, section, or field includes an unsupported character, the app will substitute a unique ID instead of the name. For example, a password saved on an item named mysql (work) would show a string of numbers and letters in place of the item name:

If you want to get secret references for every field on an item, use op item get with the --format json flag.

Example JSON output

Each field will include a line titled "reference" that contains its secret reference. For the example GitHub item, the output looks like this:

If you want to write your own secret references, use the secret reference syntax.

Step 2: Resolve secret references​

There are three ways you can replace secret references with the actual secrets they reference at runtime:

  1. Use op read to print secrets to stdout.
  2. Use op run to pass secrets as environment variables to a process.
  3. Use op inject to inject secrets into configuration files or scripts.

With op read​

You can use op read with a secret reference to print the secret to stdout.

See result...

To write the secret to a file instead of stdout, include the --out-file flag (or -o) with the path to the new file. For example, to create a file token.txt that contains the GitHub personal access token:

token.txt

You can also use op read with secret references to load secrets into scripts. For example, to use secret references in place of your Docker username and password with the docker login command:

myscript.sh

Query parameters​

You can use secret references with query parameters to get more information about an item.

To get information about item fields or file attachments, include the attribute (or attr) query parameter with the attribute you want to get.

You can query the following attributes for fields: type, value, title, id, purpose, otp

And the following attributes for file attachments: content, size, id, name, type.

For example, to retrieve a one-time password from the one-time password field on a GitHub item:

See result...

To get an SSH key's private key in the OpenSSH format, include the ssh-format query parameter with the value openssh on a secret reference for the SSH key's private key field.

See result...
Next step

Learn more about securely loading secrets into scripts.

With op run​

You can set environment variables to secret references, then use op run to pass secrets to an application or script at runtime.

op run scans environment variables for secret references, loads the corresponding values from 1Password, then runs the provided command in a subprocess with the secrets made available as environment variables for the duration of the subprocess.

Pass the secrets to an application or script​

To pass secrets to your script or application at runtime, wrap the command with op run.

For example, here's a Node.js app that needs credentials to connect to a database:

You can set the DB_USER and DB_PASSWORD environment variables to secret references:

Then use op run to pass the secrets to the node app.js command:

Use with environment files​

You can also use op run with environment files. To do this, use secret references instead of plaintext secrets in your environment file:

node.env

Then use op run with the --env-file flag:

If a subprocess used with op run prints a secret to stdout, the secret will be concealed by default. You can include the --no-masking flag to print the value.

To export an example environment variable DB_PASSWORD to a secret reference:

Use op run with the printenv command to print the concealed secret:

See result...

Include the --no-masking flag to print the actual secret:

See result...
Next step

Learn more about loading secrets into the environment with op run, including how to use template variables to switch between different sets of secrets for different environments.

With op inject​

You can use op inject to replace secret references in a script or file with the secrets they reference.

By default, op inject accepts input on stdin and outputs on stdout. You can use the --in-file flag (or -i) to read the input from a file instead, and the --out-file flag (or -o) to specify where the ouput should be written.

To use op inject to resolve a secret in a simple command:

See result...

To write the output to a file token.txt in the current directory:

token.txt

Use with configuration files​

You can use op inject to pass in a configuration file templated with secret references and output a configuration file that contains resolved secrets. Configuration files that use secret references instead of plaintext secrets can be safely checked into Git.

config.yml.tpl

Next step

Learn more about loading secrets into configuration files with op inject, including how to use template variables to switch between different sets of secrets for different environments.

Learn more​

Was this page helpful?