Secret reference syntax
Secret reference URIs point to where a secret is saved in your 1Password account using the names (or unique identifiers) of the vault, item, section, and field where the information is stored.
Secret references remove the risk of exposing plaintext secrets in your code and reflect changes you make in your 1Password account, so when you run a script you get the latest value.
You can use secret references with:
1Password integrations
Securely access your secrets in Kubernetes, CircleCI, GitHub Actions, Jenkins, Terraform, Pulumi, Postman, and more.
Learn moreGet secret references
With the 1Password desktop app
To see the option to copy secret references in the 1Password desktop app, first turn on the integration with 1Password CLI. Then:
- Open the item where the secret you want to reference is stored.
- Select next to the field that contains the secret you want to reference, then select Copy Secret Reference.
With 1Password for VS Code
You can use 1Password for VS Code to insert secret references from 1Password as you edit your code. First, install the extension. Then:
- Open the Command Palette .
- Enter
1Password: Get from 1Password. - Enter the item name or ID.
- Select the field to use.
With 1Password CLI
To get a secret reference with 1Password CLI, run op item get with the --format json flag and include the --fields flag to specify a field label. Then use jq to retrieve the secret reference from the JSON output. For example:
See result...
To get secret references for every field on an item, use op item get with the --format json flag without specifying a field.
Example JSON output
Each field object will include a reference key that contains its secret reference. For the example GitHub item, the output looks like this:
Syntax rules
Supported characters
Secret references are case-insensitive and support the following characters:
- alphanumeric characters (
a-z,A-Z,0-9) -,_,.and the whitespace character
If a secret reference includes a whitespace, enclose the secret reference in quotation marks. For example:
Any part of a secret reference that includes an unsupported character must be referred to by its unique identifier (ID) instead of its name.
To get an ID, run op item get with the output set to JSON. For example, to get the ID for a custom text field named test/:
See result...
File attachments
To reference a file attachment, use the file name in place of a field name:
Externally-set variables
If you use different sets of secrets in different environments, you can include variables within secret references and then set the variable to switch between secrets.
For example, the APP_ENV variable in the example below can be set to dev to load development credentials or prod to load production credentials, assuming the credentials are stored in 1Password vaults named dev and prod.
app.env
Learn how to use variables to switch between sets of secrets in environment files and config files.
Field and file metadata attributes
You can use secret references with query parameters to get more information about an item.
Attribute parameter
To get information about item fields and file attachments, use the
attribute (or attr) query parameter.
Fields
File attachments
Field attributes:
| Attribute | Definition |
|---|---|
type | The field's type |
value | The field's content |
id | The field's unique identifier |
purpose | The designation of a built-in field (can be "username", "password", or "notes") |
otp | Use with one-time password fields to generate a one-time password code |
File attachment attributes:
| Attribute | Definition |
|---|---|
type | The field's type |
content | The file attachment's content |
size | The size of the file attachment |
id | The file attachment's unique identifier |
name | The name of the file attachment |
For example, to retrieve an item's one-time password code:
See result...
To retrieve a field's type:
See result...
To retrieve the name of a file attachment:
See result...
SSH format parameter
To get an SSH 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...
Secret reference examples
A field inside a section
To create a secret reference that refers to the PagerDuty email field, which is within the Admin section, use:
- Management refers to the vault where the item is saved
- PagerDuty refers to the item
- Admin refers to the section where the field is a part of
- email refers to the field where the secret you want to reference is located
A field without a section
To create a secret reference for the Stripe publishable-key field, which is not part of a section, use:
- dev refers to the vault where the item is saved
- Stripe refers to the item
- publishable-key refers to the field where the secret you want to reference is located
