# 1Password Developer Documentation > Developer tools and APIs for 1Password, including CLI, SDKs (Python, JavaScript, Go), SSH & Git integration, secrets automation, service accounts, Connect server, Kubernetes operator, CI/CD integrations, Events API, and more. This file contains all documentation content in a single document following the llmstxt.org standard. ## Get started with 1Password CLI 1Password CLI brings 1Password to your terminal. Learn how to install the CLI, then integrate it with your 1Password app and sign in with Touch ID, Windows Hello, or another system authentication option. ## Step 1: Install 1Password CLI **Requirements** **Mac:** - [1Password subscription](https://1password.com/pricing/password-manager) - [1Password for Mac](https://1password.com/downloads/mac)* - macOS Big Sur 11.0.0 or later Supported shells: Bash, Zsh, sh, fish *Required to integrate 1Password CLI with the 1Password app. **Windows:** - [1Password subscription](https://1password.com/pricing/password-manager) - [1Password for Windows](https://1password.com/downloads/windows) Supported shells: PowerShell **Linux:** - [1Password subscription](https://1password.com/pricing/password-manager) - [1Password for Linux](https://1password.com/downloads/linux)* - [PolKit](https://github.com/polkit-org/polkit)* - A PolKit authentication agent running* Supported shells: Bash, Zsh, sh, fish *Required to integrate 1Password CLI with the 1Password app. **Mac:** **homebrew:** 1. To install 1Password CLI with [homebrew](https://brew.sh/): ```shell brew install 1password-cli ``` 2. Check that 1Password CLI installed successfully: ```shell op --version ``` The 1Password Homebrew cask is maintained by both Homebrew and 1Password developers in the open-source [Homebrew Cask repository. ](https://github.com/Homebrew/homebrew-cask) 1Password CLI downloads from our CDN on agilebits.net/.com domains. **Manual:** To manually install 1Password CLI on macOS: 1. Download [the latest release of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2). Learn how to [verify its authenticity](/docs/cli/verify/). 2. - **Package file**: Open `op.pkg` and install 1Password CLI in the default location (`usr/local/bin`). - **ZIP file**: Open `op.zip` and unzip the file, then move `op` to `usr/local/bin`. 3. Check that 1Password CLI was installed successfully: ```shell op --version ``` **Windows:** **winget:** 1. To install 1Password CLI with winget: ```powershell winget install 1password-cli ``` 2. Check that 1Password CLI installed successfully: ```powershell op --version ``` **Manual:** To manually install 1Password CLI on Windows: 1. Download [the latest release of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) and extract `op.exe`. Learn how to [verify its authenticity](/docs/cli/verify/). 2. Open PowerShell **as an administrator**. 3. Create a folder to move `op.exe` into. For example, `C:\Program Files\1Password CLI`. ```powershell mkdir "C:\Program Files\1Password CLI" ``` 4. Move the `op.exe` file to the new folder. ```powershell mv ".\op.exe" "C:\Program Files\1Password CLI" ``` 5. **Add the folder containing the `op.exe` file to your PATH.** **Windows 10 and later** Search for Advanced System Settings in the Start menu. Select Environment Variables. In the System Variables section, select the PATH environment variable and select Edit. In the prompt, select New and add the directory where `op.exe` is located. Sign out and back in to Windows for the change to take effect. 6. Check that 1Password CLI installed successfully: ```shell op --version ``` If you'd rather install 1Password CLI with a single block of commands, run the following in PowerShell as administrator: ```powershell $arch = (Get-CimInstance Win32_OperatingSystem).OSArchitecture switch ($arch) { '64-bit' { $opArch = 'amd64'; break } '32-bit' { $opArch = '386'; break } Default { Write-Error "Sorry, your operating system architecture '$arch' is unsupported" -ErrorAction Stop } } $installDir = Join-Path -Path $env:ProgramFiles -ChildPath '1Password CLI' Invoke-WebRequest -Uri "https://cache.agilebits.com/dist/1P/op2/pkg/v2.32.1/op_windows_$($opArch)_v2.32.1.zip" -OutFile op.zip Expand-Archive -Path op.zip -DestinationPath $installDir -Force $envMachinePath = [System.Environment]::GetEnvironmentVariable('PATH','machine') if ($envMachinePath -split ';' -notcontains $installDir){ [Environment]::SetEnvironmentVariable('PATH', "$envMachinePath;$installDir", 'Machine') } Remove-Item -Path op.zip ``` If your Windows operating system uses a language other than English, you'll need to manually set `$arch` in the first line. To do this, replace `$arch = (Get-CimInstance Win32_OperatingSystem).OSArchitecture` with `$arch = "64-bit"` or `$arch = "32-bit"`. **Linux:** **APT:** To install 1Password CLI using APT on Debian- and Ubuntu-based distributions: 1. Run the following command: ```shell curl -sS https://downloads.1password.com/linux/keys/1password.asc | \ sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg && \ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/$(dpkg --print-architecture) stable main" | \ sudo tee /etc/apt/sources.list.d/1password.list && \ sudo mkdir -p /etc/debsig/policies/AC2D62742012EA22/ && \ curl -sS https://downloads.1password.com/linux/debian/debsig/1password.pol | \ sudo tee /etc/debsig/policies/AC2D62742012EA22/1password.pol && \ sudo mkdir -p /usr/share/debsig/keyrings/AC2D62742012EA22 && \ curl -sS https://downloads.1password.com/linux/keys/1password.asc | \ sudo gpg --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg && \ sudo apt update && sudo apt install 1password-cli ``` **See a step-by-step version of the script** 1. Add the key for the 1Password `apt` repository: ```shell curl -sS https://downloads.1password.com/linux/keys/1password.asc | \ sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg ``` 2. Add the 1Password `apt` repository: ```shell echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/$(dpkg --print-architecture) stable main" | sudo tee /etc/apt/sources.list.d/1password.list ``` 3. Add the debsig-verify policy: ```shell sudo mkdir -p /etc/debsig/policies/AC2D62742012EA22/ curl -sS https://downloads.1password.com/linux/debian/debsig/1password.pol | \ sudo tee /etc/debsig/policies/AC2D62742012EA22/1password.pol && \ sudo mkdir -p /usr/share/debsig/keyrings/AC2D62742012EA22 && \ curl -sS https://downloads.1password.com/linux/keys/1password.asc | \ sudo gpg --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg ``` 4. Install 1Password CLI: ```shell sudo apt update && sudo apt install 1password-cli ``` 2. Check that 1Password CLI installed successfully: ```shell op --version ``` Alternatively, download the latest 1Password CLI `.deb` package directly from one of the following links: - [amd64](https://downloads.1password.com/linux/debian/amd64/stable/1password-cli-amd64-latest.deb) - [386](https://downloads.1password.com/linux/debian/386/stable/1password-cli-386-latest.deb) - [arm](https://downloads.1password.com/linux/debian/arm/stable/1password-cli-arm-latest.deb) - [arm64](https://downloads.1password.com/linux/debian/arm64/stable/1password-cli-arm64-latest.deb) **YUM:** To install 1Password CLI using YUM on RPM-based distributions: 1. Run the following commands: ```shell sudo rpm --import https://downloads.1password.com/linux/keys/1password.asc sudo sh -c 'echo -e "[1password]\nname=1Password Stable Channel\nbaseurl=https://downloads.1password.com/linux/rpm/stable/\$basearch\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=\"https://downloads.1password.com/linux/keys/1password.asc\"" > /etc/yum.repos.d/1password.repo' sudo dnf check-update -y 1password-cli && sudo dnf install 1password-cli ``` **The above script is comprised of the following steps** 1. Import the public key: ```shell sudo rpm --import https://downloads.1password.com/linux/keys/1password.asc ``` 2. Configure the repository information: ```shell sudo sh -c 'echo -e "[1password]\nname=1Password Stable Channel\nbaseurl=https://downloads.1password.com/linux/rpm/stable/\$basearch\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=\"https://downloads.1password.com/linux/keys/1password.asc\"" > /etc/yum.repos.d/1password.repo' ``` 3. Install 1Password CLI: ```shell sudo dnf check-update -y 1password-cli && sudo dnf install 1password-cli ``` 2. Check that 1Password CLI installed successfully: ```shell op --version ``` Alternatively, download the latest 1Password CLI `.rpm` package directly from one of the following links: - [x86_64](https://downloads.1password.com/linux/rpm/stable/x86_64/1password-cli-latest.x86_64.rpm) - [i386](https://downloads.1password.com/linux/rpm/stable/i386/1password-cli-latest.i386.rpm) - [aarch64](https://downloads.1password.com/linux/rpm/stable/aarch64/1password-cli-latest.aarch64.rpm) - [armv7l](https://downloads.1password.com/linux/rpm/stable/armv7l/1password-cli-latest.armv7l.rpm) **Alpine:** To install 1Password CLI on Alpine x86_64 distributions: 1. Run the following commands: ```shell echo https://downloads.1password.com/linux/alpinelinux/stable/ >> /etc/apk/repositories wget https://downloads.1password.com/linux/keys/alpinelinux/support@1password.com-61ddfc31.rsa.pub -P /etc/apk/keys apk update && apk add 1password-cli ``` **The above script is comprised of the following steps** 1. Add Password CLI to your list of repositories: ```shell echo https://downloads.1password.com/linux/alpinelinux/stable/ >> /etc/apk/repositories ``` 2. Add the public key to validate the APK to your keys directory: ```shell wget https://downloads.1password.com/linux/keys/alpinelinux/support@1password.com-61ddfc31.rsa.pub -P /etc/apk/keys ``` 3. Install 1Password CLI: ```shell apk update && apk add 1password-cli ``` 2. Check that 1Password CLI installed successfully: ```shell op --version ``` **NixOS:** :::warning[caution] The Nix package is available from the NixOS open source community. ::: To install 1Password CLI on your NixOS system: 1. Add 1Password to your `/etc/nixos/configuration.nix` file, or `flake.nix` if you're using a flake. For example, the following snippet includes 1Password CLI and the 1Password app: ```nix # NixOS has built-in modules to enable 1Password # along with some pre-packaged configuration to make # it work nicely. You can search what options exist # in NixOS at https://search.nixos.org/options # Enables the 1Password CLI programs._1password = { enable = true; }; # Enables the 1Password desktop app programs._1password-gui = { enable = true; # this makes system auth etc. work properly polkitPolicyOwners = [ "" ]; }; ``` 2. After you make changes to your configuration file, apply them: - If you added 1Password to `/etc.nixos/configuration.nix`, run: ```shell sudo nixos-rebuild switch ``` - If you added 1Password to `flake.nix`, replace `` with the directory your flake is in and `` with the name of the flake output containing your system configuration, then run the command. ```shell sudo nixos-rebuild switch --flake .# ``` 3. Check that 1Password CLI installed successfully: ```shell op --version ``` Learn more about [using 1Password on NixOS. ](https://nixos.wiki/wiki/1Password) **Manual:** To install 1Password CLI on Linux without a package manager: ```shell ARCH="" && \ wget "https://cache.agilebits.com/dist/1P/op2/pkg/v2.32.1/op_linux_${ARCH}_v2.32.1.zip" -O op.zip && \ unzip -d op op.zip && \ sudo mv op/op /usr/local/bin/ && \ rm -r op.zip op && \ sudo groupadd -f onepassword-cli && \ sudo chgrp onepassword-cli /usr/local/bin/op && \ sudo chmod g+s /usr/local/bin/op ``` **Or follow the extended guide** 1. Download the [latest release of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) and extract it. To verify its authenticity: ```shell gpg --keyserver keyserver.ubuntu.com --receive-keys 3FEF9748469ADBE15DA7CA80AC2D62742012EA22 gpg --verify op.sig op ``` 2. Move `op` to `/usr/local/bin`, or another directory in your `$PATH`. 3. Check that 1Password CLI installed successfully: ```shell op --version ``` 4. Create the `onepassword-cli` group if it doesn't yet exist: ```shell sudo groupadd onepassword-cli ``` 5. Set the correct permissions on the `op` binary: ```shell sudo chgrp onepassword-cli /usr/local/bin/op && \ sudo chmod g+s /usr/local/bin/op ``` ## Step 2: Turn on the 1Password desktop app integration **Mac:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 4. Select **Integrate with 1Password CLI**. 5. If you want to authenticate 1Password CLI with your fingerprint, turn on **[Touch ID](https://support.1password.com/touch-id-mac/)** in the app. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ **Windows:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Turn on **[Windows Hello](https://support.1password.com/windows-hello/)** in the app. 4. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 5. Select **Integrate with 1Password CLI**. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ **Linux:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Security](onepassword://settings/security)**. 4. Turn on **[Unlock using system authentication](https://support.1password.com/system-authentication-linux/)**. 5. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 6. Select **Integrate with 1Password CLI**. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ [Learn more about the 1Password desktop app integration.](/docs/cli/app-integration/) ## Step 3: Enter any command to sign in After you've turned on the app integration, enter any command and you'll be prompted to authenticate. For example, run this command to see all the vaults in your account: ```shell op vault list ``` #### If you have multiple accounts If you've added multiple 1Password accounts to your desktop app, you can use [`op signin`](/docs/cli/reference/commands/signin/) to select an account to sign in to with 1Password CLI. Use the arrow keys to choose from the list of all accounts added to your 1Password app. ```shell {2} op signin #code-result Select account [Use arrows to move, type to filter] > ACME Corp (acme.1password.com) AgileBits (agilebits.1password.com) Add another account ``` [Learn more about using multiple accounts with 1Password CLI.](/docs/cli/use-multiple-accounts/) ## Next steps 1. [Get started with basic 1Password CLI commands.](/docs/cli/reference/) 2. [Set up 1Password Shell Plugins to handle authentication for your other command-line tools.](/docs/cli/shell-plugins/) 3. [Learn how to securely load secrets from your 1Password account without putting any plaintext secrets in code.](/docs/cli/secret-references/) ## Learn more - [1Password app integration troubleshooting](/docs/cli/app-integration#troubleshooting) - [1Password app integration security](/docs/cli/app-integration-security/) - [How 1Password CLI detects configuration directories](/docs/cli/config-directories) --- ## account | 1Password CLI # account Manage your locally configured 1Password accounts. ### Subcommands {#subcommands} - [account add](#account-add): Add an account to sign in to for the first time - [account forget](#account-forget): Remove a 1Password account from this device - [account get](#account-get): Get details about your account - [account list](#account-list): List users and accounts set up on this device ## account add Add a new 1Password account to 1Password CLI manually with your account password and Secret Key, instead of [signing in using your 1Password app](/docs/cli/app-integration/). ```shell op account add [flags] ``` ### Flags {#account-add-flags} ``` --address string The sign-in address for your account. --email string The email address associated with your account. --raw Only return the session token. --shorthand string Set a custom account shorthand for your account. --signin Immediately sign in to the added account. ``` To sign in to manually-added accounts: **Bash, Zsh, sh, fish:** ```shell eval $(op signin) ``` **PowerShell:** ```powershell Invoke-Expression $(op signin) ``` [Learn more about signing in manually.](/docs/cli/sign-in-manually/) When you sign in manually, 1Password CLI creates a session token and sets the `OP_SESSION` environment variable to it. Session tokens expire after 30 minutes of inactivity, after which you’ll need to sign in again. If you add multiple 1Password accounts, 1Password CLI determines which to use in this order: 1. An account specified with the `--account` flag. 2. An account specified with the `OP_ACCOUNT` environment variable. 3. The account most recently signed in to with `op signin` in the current terminal window. ### Examples {#examples} Add an account using flags to specify account details: ```shell op account add --address my.1password.com --email user@example.org ``` Add an account and immediately sign in to it: **Bash, Zsh, sh, fish:** ```shell eval $(op account add --signin) ``` **PowerShell:** ```powershell Invoke-Expression $(op account add --signin) ``` Sign in to a specific account: **Bash, Zsh, sh, fish:** ```shell eval $(op signin --account my) ``` **PowerShell:** ```powershell Invoke-Expression $(op signin --account my) ``` ## account forget Remove a 1Password account from this device. ``` op account forget [ ] [flags] ``` ### Flags {#account-forget-flags} ``` --all Forget all authenticated accounts. ``` ## account get Get details about your account. ``` op account get [flags] ``` ## account list List users and accounts set up on this device. ``` op account list [flags] ``` --- ## completion | 1Password CLI # completion Generate shell completion information for 1Password CLI. ```shell op completion [flags] ``` If you use Bash, Zsh, fish, or PowerShell, you can add shell completion for 1Password CLI. With completions loaded, after you start typing a command, press Tab to see available commands and options. #### Load shell completion information for Bash To always load the completion information for Bash, add this to your `.bashrc` file: ```shell source <(op completion bash) ``` To use shell completion in Bash, you’ll need the `bash-completion` package. #### Load shell completion information for Zsh To always load the completion information for Zsh, add this to your `.zshrc` file: ```shell eval "$(op completion zsh)"; compdef _op op ``` #### Load shell completion information for fish To always load the completion information for fish, add this to your `.fish` file: ```shell op completion fish | source ``` #### Load shell completion information for PowerShell To always load the completion information for PowerShell, add this to your `.ps1` file: ```powershell op completion powershell | Out-String | Invoke-Expression ``` :::note To use shell completion in PowerShell, you need to enable execution of scripts. To do that, start a PowerShell window as administrator and run the following command: ::: ```powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned ``` --- ## connect | 1Password CLI # connect Manage Connect server instances and tokens in your 1Password account. :::tip Looking up a Connect server by its [ID](/docs/cli/reference#unique-identifiers-ids) is more efficient than using the Connect server's name. ::: ### Subcommands {#subcommands} - [connect group](#connect-group): Manage group access to Secrets Automation - [connect server](#connect-server): Manage Connect servers - [connect token](#connect-token): Manage Connect server tokens - [connect vault](#connect-vault): Manage Connect server vault access ## connect group ### Subcommands {#connect-group-subcommands} - [connect group grant](#connect-group-grant): Grant a group access to manage Secrets Automation - [connect group revoke](#connect-group-revoke): Revoke a group's access to manage Secrets Automation ## connect group grant Grant a group access to manage Secrets Automation. ``` op connect group grant [flags] ``` ### Flags {#connect-group-grant-flags} ``` --all-servers Grant access to all current and future servers in the authenticated account. --group group The group to receive access. --server server The server to grant access to. ``` If you don't specify a server, it adds the group to the list of Secrets Automation managers. ## connect group revoke Revoke a group's access to manage Secrets Automation. ``` op connect group revoke [flags] ``` ### Flags {#connect-group-revoke-flags} ``` --all-servers Revoke access to all current and future servers in the authenticated account. --group group The group to revoke access from. --server server The server to revoke access to. ``` ## connect server ### Subcommands {#connect-server-subcommands} - [connect server create](#connect-server-create): Set up a Connect server - [connect server delete](#connect-server-delete): Remove a Connect server - [connect server edit](#connect-server-edit): Rename a Connect server - [connect server get](#connect-server-get): Get a Connect server - [connect server list](#connect-server-list): List Connect servers ## connect server create Add a 1Password Connect server to your account and generate a credentials file for it. 1Password CLI saves the `1password-credentials.json` file in the current directory. Note: You can't grant a Connect server access to your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault. ``` op connect server create [flags] ``` ### Flags {#connect-server-create-flags} ``` -f, --force Do not prompt for confirmation when overwriting credential files. --vaults strings Grant the Connect server access to these vaults. ``` 1Password CLI saves the `1password-credentials.json` file in the current directory. ## connect server delete Remove a Connect server. Specify the server by name or ID. ``` op connect server delete [{ | | - }] [flags] ``` The credentials file and all the tokens for the server will no longer be valid. ## connect server edit Rename a Connect server. Specify the server by name or ID. ``` op connect server edit { | } [flags] ``` ### Flags {#connect-server-edit-flags} ``` --name name Change the server's name. ``` ## connect server get Get details about a Connect server. Specify the server by name or ID. ``` op connect server get [{ | | - }] [flags] ``` ## connect server list Get a list of Connect servers. ``` op connect server list [flags] ``` ## connect token ### Subcommands {#connect-token-subcommands} - [connect token create](#connect-token-create): Issue a token for a 1Password Connect server - [connect token delete](#connect-token-delete): Revoke a token for a Connect server - [connect token edit](#connect-token-edit): Rename a Connect server token - [connect token list](#connect-token-list): Get a list of tokens ## connect token create Issue a new token for a Connect server. ``` op connect token create [flags] ``` ### Flags {#connect-token-create-flags} ``` --expires-in duration Set how long the Connect token is valid for in (s)econds, (m)inutes, (h)ours, (d)ays, and/or (w)eeks. --server string Issue a token for this server. --vault stringArray Issue a token on these vaults. ``` Returns a token. You can only provision Connect server tokens to vaults that the Connect server has access to. Use `op connect vault grant` to grant access to vaults. Note: You can't grant a Connect server access to your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault. By default, the `--vaults` option grants the same permissions as the server. To further limit the permissions a token has to read-only or write-only, add a comma and `r` or `w` after the vault specification. For example: ``` op connect token create "Dev k8s token" --server Dev --vaults Kubernetes,r \ --expires-in=30d ``` ``` op connect token create "Prod: Customer details" --server Prod --vault "Customers,w" \ --vault "Vendors,r" ``` ## connect token delete Revoke a token for a Connect server. ``` op connect token delete [ ] [flags] ``` ### Flags {#connect-token-delete-flags} ``` --server string Only look for tokens for this 1Password Connect server. ``` ## connect token edit Rename a Connect server token. ``` op connect token edit [flags] ``` ### Flags {#connect-token-edit-flags} ``` --name string Change the token's name. --server string Only look for tokens for this 1Password Connect server. ``` ## connect token list List tokens for Connect servers. ``` op connect token list [flags] ``` ### Flags {#connect-token-list-flags} ``` --server server Only list tokens for this Connect server. ``` Returns both active and revoked tokens. The `integrationId` is the ID for the Connect server the token belongs to. ## connect vault ### Subcommands {#connect-vault-subcommands} - [connect vault grant](#connect-vault-grant): Grant a Connect server access to a vault - [connect vault revoke](#connect-vault-revoke): Revoke a Connect server's access to a vault ## connect vault grant Grant a Connect server access to a vault. ``` op connect vault grant [flags] ``` Note: You can't grant a Connect server access to your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault. ### Flags {#connect-vault-grant-flags} ``` --server string The server to be granted access. --vault string The vault to grant access to. ``` ## connect vault revoke Revoke a Connect server's access to a vault. ``` op connect vault revoke [flags] ``` ### Flags {#connect-vault-revoke-flags} ``` --server server The server to revoke access from. --vault vault The vault to revoke a server's access to. ``` --- ## document | 1Password CLI # document Perform CRUD operations on Document items in your vaults. ### Subcommands {#subcommands} - [document create](#document-create): Create a document item - [document delete](#document-delete): Delete or archive a document item - [document edit](#document-edit): Edit a document item - [document get](#document-get): Download a document - [document list](#document-list): Get a list of documents ## document create Create a document item and receive a JSON object that contains the item's ID. ``` op document create [{ | - }] [flags] ``` ### Flags {#document-create-flags} ``` --file-name name Set the file's name. --tags tags Set the tags to the specified (comma-separated) values. --title title Set the document item's title. --vault vault Save the document in this vault. Default: Private. ``` By default, the document is saved in your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault. Specify a different vault with the `--vault` option. #### Create a file from standard input To create the file contents from standard input (stdin), enter a hyphen (`-`) instead of a path. You can use the `--file-name` option to change the name of the file. ### Examples {#document-create-examples} Create a document by specifying the file path: ``` op document create "../demos/videos/demo.mkv" --title "2020-06-21 Demo Video" ``` Create a document from standard input: ``` cat auth.log.* | op document create - --title "Authlogs 2020-06" --file-name "auth.log.2020.06" ``` ## document delete Permanently delete a document. Specify the document to delete by its name or ID. Use the `--archive` option to move it to the Archive instead. ``` op document delete [{ | | - }] [flags] ``` ### Flags {#document-delete-flags} ``` --archive Move the document to the Archive. --vault vault Delete the document in this vault. ``` #### Specify items on standard input The command treats each line of information on standard input (stdin) as an object specifier. Run `op help` to learn more about how to specify objects. You can also input a list or array of JSON objects. The command will get an item for any object that has an ID. This is useful for passing information from one `op` command to another. ### Examples {#document-delete-examples} Permanently delete a document: ``` op document delete "2019 Contracts" ``` Move a document to the Archive: ``` op document delete "2019 Contracts" --archive ``` ## document edit Edit a document item. Specify the document item to edit by its name or ID. ``` op document edit { | } [{ | - }] [flags] ``` ### Flags {#document-edit-flags} ``` --file-name name Set the file's name. --tags tags Set the tags to the specified (comma-separated) values. An empty value removes all tags. --title title Set the document item's title. --vault vault Look up document in this vault. ``` Replaces the file contents of a Document item with the provided file or with the information on standard input (stdin). #### Update a file from standard input To update the file contents from standard input (stdin), enter a hyphen (`-`) instead of a path. You can use the `--file-name` option to change the name of the file. ## document get Download a document and print the contents. Specify the document by its name or ID. ``` op document get { | } [flags] ``` ### Flags {#document-get-flags} ``` --file-mode filemode Set filemode for the output file. It is ignored without the --out-file flag. (default 0600) --force Forcibly print an unintelligible document to an interactive terminal. If --out-file is specified, save the document to a file without prompting for confirmation. --include-archive Include document items in the Archive. Can also be set using OP_INCLUDE_ARCHIVE environment variable. -o, --out-file path Save the document to the file path instead of stdout. --vault vault Look for the document in this vault. ``` Prints to standard output (stdout) by default. To print to a file, use the `--out-file path/to/file.ext` flag. #### Save to a file Use the `--out-file` option to have `op` save the document. This may be useful in some shells as a way to preserve the file's original encoding. The `--out-file` option won't overwrite an existing file. The destination path must be an empty file or not exist. ### Examples {#document-get-examples} Save a document to a file called `secret-plans.text`: ``` op document get "Top Secret Plan B" --out-file=../documents/secret-plans.text ``` ## document list List documents. ``` op document list [flags] ``` ### Flags {#document-list-flags} ``` --include-archive Include document items in the Archive. Can also be set using OP_INCLUDE_ARCHIVE environment variable. --vault vault Only list documents in this vault. ``` Returns a list of all documents the account has read access to by default. Excludes items in the Archive by default. --- ## environment | 1Password CLI # environment (Beta) :::note The `--environments` flag is available in [the latest beta build of 1Password CLI](/docs/cli/reference#beta-builds), version `2.33.0-beta.02` or later. ::: [1Password Environments](/docs/environments) allow you to organize and manage your project's environment variables, separately from the rest of the items in your 1Password vaults. You can create an Environment for each project or development stage, then securely access your variables directly from 1Password when you need them. ### Subcommands {#subcommands} - [environment read](#environment-read): Read environment variables from a 1Password Environment ## environment read Read environment variables from a 1Password Environment. ```shell op environment read [flags] ``` Specify the 1Password Environment by its ID. To find an Environment's ID, open the 1Password app, navigate to **Developer** > **View Environments** > then select **View environment** > **Manage environment** > **Copy environment ID**. ### Examples {#environment-read-examples} Read variables from a 1Password Environment: ```shell op environment read ``` --- ## events-api | 1Password CLI # events-api Manage Events API integrations in your 1Password account. Requires a business account. ### Subcommands {#subcommands} - [events-api create](#events-api-create): Set up an integration with the Events API ## events-api create Create an Events API integration token. ``` op events-api create [flags] ``` ### Flags {#events-api-create-flags} ``` --expires-in duration Set how the long the events-api token is valid for in (s)econds, (m)inutes, (h)ours, (d)ays, and/or (w)eeks. --features features Set the comma-separated list of features the integration token can be used for. Options: `signinattempts`, `itemusages`, `auditevents`. ``` 1Password CLI prints the token when successful. Requires a business account. ### Examples {#events-api-create-examples} Create an Events API integration to report sign-in attempts that expires in one hour: ``` op events-api create SigninEvents --features signinattempts --expires-in 1h ``` Create an Events API integration that reports all supported events that does not expire: ``` op events-api create AllEvents ``` --- ## group | 1Password CLI # group Manage the groups in your 1Password account. Groups can be used to organize your team and delegate administrative responsibilities. You can give groups access to vaults and assign them permissions, so you don't have to keep track of everyone separately. ### Subcommands {#subcommands} - [group create](#group-create): Create a group - [group delete](#group-delete): Remove a group - [group edit](#group-edit): Edit a group's name or description - [group get](#group-get): Get details about a group - [group list](#group-list): List groups - [group user](#group-user): Manage group membership ## group create Create a group and receive a JSON object with the group's ID. ``` op group create [flags] ``` ### Flags {#group-create-flags} ``` --description string Set the group's description. ``` ## group delete Remove a group. Specify the group to delete by its name or ID. ``` op group delete [{ | | - }] [flags] ``` ## group edit Edit a group's name or description. Specify the group to edit by its name or ID. ``` op group edit [{ | | - }] [flags] ``` ### Flags {#group-edit-flags} ``` --description description Change the group's description. --name name Change the group's name. ``` ## group get Get details about a group. Specify the group by its name or ID. ``` op group get [{ | | - }] [flags] ``` #### Use standard input to specify objects If you enter a hyphen (`-`) instead of a single object for this command, the tool will read object specifiers from standard input (stdin). Separate each specifier with a new line. For more information about how to specify objects, run `op help`. You can also pass the command a list or array of JSON objects. The tool will get an item for any object that has an ID, ignoring line breaks. This is useful for passing information from one `op` command to another. ### Examples {#group-get-examples} Get details for all groups: ``` op group list --format=json | op group get - ``` Get details for the groups who have access to a vault: ``` op group list --vault "Production keys" --format=json | op group get - ``` ## group list List groups. ``` op group list [flags] ``` ### Flags {#group-list-flags} ``` --user user List groups that a user belongs to. --vault vault List groups that have direct access to a vault. ``` Returns all groups in an account by default. ### Examples {#group-list-examples} Get details for all groups: ``` op group list | op group get - ``` Get details for the groups that have access to a vault: ``` op group list --vault Staging --format=json | op group get - ``` Get details for the groups that a user belongs to: ``` op group list --user wendy_appleseed@1password.com --format=json | op group get - ``` ## group user ### Subcommands {#group-user-subcommands} - [group user grant](#group-user-grant): Add a user to a group - [group user list](#group-user-list): Retrieve users that belong to a group - [group user revoke](#group-user-revoke): Remove a user from a group ## group user grant Grant a user access to a group. ``` op group user grant [flags] ``` ### Flags {#group-user-grant-flags} ``` --group string Specify the group to grant the user access to. --role string Specify the user's role as a member or manager. Default: member. --user string Specify the user to grant group access to. ``` ## group user list Retrieve users that belong to a group. ``` op group user list [flags] ``` ## group user revoke Revoke a user's access to a group. ``` op group user revoke [flags] ``` ### Flags {#group-user-revoke-flags} ``` --group string Specify the group to remove the user from. --help Get help with group user revoke. --user string Specify the user to remove from the group. ``` --- ## inject | 1Password CLI # inject Inject secrets into a file templated with secret references. ``` op inject [flags] ``` ### Flags {#flags} ``` --file-mode filemode Set filemode for the output file. It is ignored without the --out-file flag. (default 0600) -f, --force Do not prompt for confirmation. -i, --in-file string The filename of a template file to inject. -o, --out-file string Write the injected template to a file instead of stdout. ``` [Learn more about secret references.](/docs/cli/secret-references) You can pass in a config file templated with secret references and receive a config file with the actual secrets substituted. Make sure to delete the resolved file when you no longer need it. [Learn more about loading secrets into config files.](/docs/cli/secrets-config-files) ### Examples {#examples} Inject secrets into a config template from stdin: ``` echo "db_password: {{ op://app-prod/db/password }}" | op inject db_password: fX6nWkhANeyGE27SQGhYQ ``` Inject secrets into a config template file: ``` cat config.yml.tpl db_password: {{ op://app-prod/db/password }} ``` ``` op inject -i config.yml.tpl -o config.yml && cat config.yml db_password: fX6nWkhANeyGE27SQGhYQ ``` Multiple secrets can be concatenated: ``` echo "db_url: postgres://{{ op://lcl/db/user }}:{{ op://lcl/db/pw }}@{{ op://lcl/db/host }}:{{ op://lcl/db/port }}/{{ op://my-app-prd/db/db }}" | op inject db_url: postgres://admin:admin@127.0.0.1:5432/my-app" ``` Use variables in secret references to switch between different sets of secrets for different environments: ``` echo "db_password: op://$env/db/password" | env=prod op inject db_password: fX6nWkhANeyGE27SQGhYQ ``` --- ## item | 1Password CLI # item Perform CRUD operations on the 1Password items in your vaults. ### Subcommands {#subcommands} - [item create](#item-create): Create an item - [item delete](#item-delete): Delete or archive an item - [item edit](#item-edit): Edit an item's details - [item get](#item-get): Get an item's details - [item list](#item-list): List items - [item move](#item-move): Move an item between vaults - [item share](#item-share): Share an item - [item template](#item-template): Manage templates ## item create Create a new item. ``` op item create [ - ] [ ... ] [flags] ``` ### Flags {#item-create-flags} ``` --category category Set the item's category. --dry-run Test the command and output a preview of the resulting item. --favorite Add item to favorites. --generate-password[=recipe] Add a randomly-generated password to a Login or Password item. --reveal Don't conceal sensitive fields. --ssh-generate-key The type of SSH key to create: Ed25519 or RSA. For RSA, specify 2048, 3072, or 4096 (default) bits. Possible values: ed25519, rsa, rsa2048, rsa3072, rsa4096. (default Ed25519) --tags tags Set the tags to the specified (comma-separated) values. --template string Specify the filepath to read an item template from. --title title Set the item's title. --url URL Set the website where 1Password suggests and fills a Login, Password, or API Credential item. --vault vault Save the item in this vault. Default: Private. ``` Get a list of all item categories: ```shell op item template list ``` Use assignment statements or an item category JSON template to save details in built-in or custom fields. [Learn more about creating items.](/docs/cli/item-create/) [Learn more about item fields and fieldTypes.](/docs/cli/item-fields/) #### Generate a password Use the `--generate-password` option to set a random password for a Login or Password item. The default is 32-characters, and includes upper and lowercase letters, numbers, and symbols (`!@.-_*`). You can specify the password length (between 1 and 64 characters) and the character types to use: ```shell --generate-password='letters,digits,symbols,32' ``` #### Set additional fields with assignment statements You can use assignment statements as command arguments to set built-in and custom fields. ``` [
.][[]]= ``` Command arguments get logged in your command history, and can be visible to other processes on your machine. If you’re assigning sensitive values, use a JSON template instead. For example, to create a text field named "host" within a section named "Database Credentials", with the value set to 33.166.240.221: ```shell DatabaseCredentials.host[text]=33.166.240.221 ``` The section name is optional unless multiple sections contain fields with the same name. Use a backslash to escape periods, equal signs, or backslashes in section or field names. Don’t use backslashes to escape the value. You can omit spaces in the section or field name, or refer to the field by its JSON short name (`name` or `n`). #### Create an item using a json template Use an item JSON template to assign sensitive values to an item. If you combine a template with assignment statements, assignment statements take precedence. 1. Save the appropriate item category template to a file: ```shell op item template get --out-file login.json "Login" ``` 2. Edit the template. 3. Create a new item using the `-—template` flag to specify the path to the edited template: ```shell op item create --template=login.json ``` 4. After 1Password CLI creates the item, delete the edited template. You can also create an item from standard input using an item JSON template. Pass the `-` character as the first argument, followed by any assignment statements. ```shell op item template get Login | op item create --vault personal - ``` You can’t use both piping and the `--template` flag in the same command, to avoid collisions. ### Examples {#item-create-examples} Create a Login item with a random password and website set using flags and custom and built-in fields set with assignment statements, including a one-time password field and a file attachment: ```shell op item create --category=login --title='My Example Item' --vault='Test' \ --url https://www.acme.com/login \ --generate-password=20,letters,digits \ username=jane@acme.com \ 'Test Section 1.Test Field3[otp]=otpauth://totp/:?secret=&issuer=' \ 'FileName[file]=/path/to/your/file' ``` Create an item by duplicating an existing item from another vault and modifying it with assignment statements: ```shell op item get "My Item" --format json | op item create --vault prod - \ username="My Username" password="My Password" ``` Duplicate all items in a vault in one account to a vault in another account: ```shell op item list --vault test-vault --format json --account agilebits | \ op item get --format json --account agilebits - | \ op item create --account work - ``` ## item delete Delete or archive items you no longer need. ``` op item delete [{ | | | - }] [flags] ``` ### Flags {#item-delete-flags} ``` --archive Move the item to the Archive. --vault string Look for the item in this vault. ``` Deleted items remain available for 30 days in Recently Deleted. You can restore or permanently delete items from Recently Deleted in the 1Password apps. Use the `--archive` option to move an item to the Archive instead. Specify an item to delete or archive by its name, ID, or sharing link. #### Specify items on standard input The command treats each line of information on standard input (stdin) as an object specifier. Run `op help` to learn more about how to specify objects. The input can also be a list or array of JSON objects. The command will get an item for any object that has an ID. This is useful for passing information from one `op` command to another. ### Examples {#item-delete-examples} Delete an item: ``` op item delete "Defunct Login" ``` Move an item to the Archive: ``` op item delete "Defunct Login" --archive ``` ## item edit Edit an item's details. ``` op item edit { | | } [ ... ] [flags] ``` ### Flags {#item-edit-flags} ``` --dry-run Perform a dry run of the command and output a preview of the resulting item. --favorite Whether this item is a favorite item. Options: true, false. --generate-password[=recipe] Give the item a randomly generated password. --reveal Don't conceal sensitive fields. --tags tags Set the tags to the specified (comma-separated) values. An empty value will remove all tags. --template string Specify the filepath to read an item template from. --title title Set the item's title. --url URL Set the website where 1Password suggests and fills a Login, Password, or API Credential item. --vault vault Edit the item in this vault. ``` Specify the item by its name, ID, or sharing link. Use flags to update the title, tags, or generate a new random password. You can use assignment statements as command arguments to update built-in or custom fields. For sensitive values, use a template instead. #### Edit an item using assignment statements Caution: Command arguments can be visible to other processes on your machine. ```shell [
.][[]]= ``` To create a new field or section, specify a field or section name that doesn’t already exist on the item. To edit an existing field, specify the current section and field name, then make changes to the fieldType or value. If you don’t specify a fieldType or value, it will stay the same. To delete a custom field, specify `[delete]` in place of the fieldType. If a section no longer has any fields, the section will also be deleted. You can't delete built-in fields, but you can set them to empty strings. Learn more about assignment statements: `op item create –-help`. [Learn more about available fields and fieldTypes.](/docs/cli/item-fields) #### Edit an item using a template :::danger JSON item templates do not support passkeys. If you use a JSON template to update an item that contains a passkey, the passkey will be overwritten. To fix this, you can [restore a previous version of the item](https://support.1password.com/item-history/). ::: You can use a JSON template to edit an item, alone or in combination with command arguments. Field assignment statements overwrite values in the template. 1. Get the item you want to edit in JSON format and save it to a file: ``` op item get oldLogin --format=json > updatedLogin.json ``` 2. Edit the file. 3. Use the `--template` flag to specify the path to the edited file and edit the item: op item edit oldLogin --template=updatedLogin.json 4. Delete the file. You can also edit an item using piped input: ```shell cat updatedLogin.json | op item edit oldLogin ``` To avoid collisions, you can't combine piped input and the `--template` flag in the same command. ### Examples {#item-edit-examples} Add a 32-character random password that includes upper- and lower-case letters, numbers, and symbols to an item: ```shell op item edit 'My Example Item' --generate-password='letters,digits,symbols,32' ``` Edit a custom field's value without changing the fieldType: ``` op item edit 'My Example Item' 'field1=new value' ``` Edit a custom field's fieldType without changing the value: ``` op item edit 'My Example Item' 'field1[password]' ``` Edit a custom field's type and value: ``` op item edit 'My Example Item' 'field1[monthyear]=2021/09' ``` Add a new custom field to an item: ``` op item edit 'My Example Item' 'section2.field5[phone]=1-234-567-8910' ``` Remove an existing custom field: ``` op item edit 'My Example Item' 'section2.field5[delete]' ``` Set the built-in username field to an empty value: ``` op item edit 'My Example Item' 'username=' ``` Edit an item using a template alongside command arguments and assignment statements: ```shell op item edit oldLogin --vault Private 'username=Lucky' --template=updatedLogin.json ``` ## item get Get details about an item. Specify the item by its name, ID, or sharing link. ``` op item get [{ | | | - }] [flags] ``` ### Flags {#item-get-flags} ``` --fields strings Return data from specific fields. Use `label=` to get the field by name or `type=` to filter fields by type. Specify multiple in a comma-separated list. --include-archive Include items in the Archive. Can also be set using OP_INCLUDE_ARCHIVE environment variable. --otp Output the primary one-time password for this item. --reveal Don't conceal sensitive fields. --share-link Get a shareable link for the item. --vault vault Look for the item in this vault. ``` If you have multiple items with the same name, or if you’re concerned about API rate limits, specify the item by its ID or limit the scope of the search with the `--vault` flag. [Learn more about IDs and caching.](/docs/cli/reference) To retrieve the contents of a specific field, use `op read` instead. When using service accounts, you must specify a vault with the `--vault` flag or through piped input. #### Specify items on standard input `op item get` treats each line of information on standard input (stdin) as an object specifier. You can also input a list or array of JSON objects, and the command will get an item for any object that has an ID key. This is useful for passing information from one command to another. #### Items in the archive Items in the Archive are ignored by default. To get details for an item in the Archive, specify the item by ID or use the `--include-archive` option. ### Examples {#item-get-examples} Get details for all items with a specified tag: ``` op item list --tags documentation --format json | op item get - ``` Get a CSV list of the username, and password for all logins in a vault: ``` op item list --categories Login --vault Staging --format json | op item get - --fields label=username,label=password ``` Get a JSON object of an item's username and password fields: ``` op item get Netflix --fields label=username,label=password --format json ``` Get a list of fields by type: ``` op item get Netflix --fields type=concealed ``` Get an item's one-time password: ``` op item get Google --otp ``` Retrieve a shareable link for the item referenced by ID: ``` op item get kiramv6tpjijkuci7fig4lndta --vault "Ops Secrets" --share-link ``` ## item list List items. ``` op item list [flags] ``` ### Flags {#item-list-flags} ``` --categories categories Only list items in these categories (comma-separated). --favorite Only list favorite items. --include-archive Include items in the Archive. Can also be set using OP_INCLUDE_ARCHIVE environment variable. --long Output a more detailed item list. --tags tags Only list items with these tags (comma-separated). --vault vault Only list items in this vault. ``` Returns a list of all items the account has read access to by default. Use flags to filter results. Excludes items in the Archive by default. Categories are: - API Credential - Bank Account - Credit Card - Database - Document - Driver License - Email Account - Identity - Login - Membership - Outdoor License - Passport - Password - Reward Program - Secure Note - Server - Social Security Number - Software License - Wireless Router ### Examples {#item-list-examples} Get details for all items with a specified tag: ``` op item list --tags documentation --format=json | op item get - ``` Get a CSV list of the username, and password for all logins in a vault: ``` op item list --categories Login --vault Staging --format=json | op item get - --fields username,password ``` Selecting a tag `` will also return items with tags sub-nested to ``. For example: ``. ## item move Move an item between vaults. Moving an item creates a copy of the item in the destination vault and deletes the item from the current vault. As a result, the item gets a new ID. ``` op item move [{ | | | - }] [flags] ``` ### Flags {#item-move-flags} ``` --current-vault string Vault where the item is currently saved. --destination-vault string The vault you want to move the item to. --reveal Don't conceal sensitive fields. ``` To restore or permanently delete the original item, find the item in Recently Deleted in your 1Password app or on 1Password.com. Moving an item between vaults may change who has access to the item. ### Examples {#item-move-examples} Move an item from the Private vault to the Shared vault: ``` op item move "My Example Item" --current-vault Private --destination-vault Shared ``` ## item share Share an item. ``` op item share { | } [flags] ``` ### Flags {#item-share-flags} ``` --emails strings Email addresses to share with. --expires-in duration Expire link after the duration specified in (s)econds, (m)inutes, (h)ours, (d)ays, and/or (w)eeks. (default 7d) --vault string Look for the item in this vault. --view-once Expire link after a single view. ``` You can securely share copies of passwords and other items you've saved in 1Password with anyone, even if they don't use 1Password. When you share an item, you'll get a unique link that you can send to others. Copy the URL, then send the link to the person or people you want to share the item copy with, like in an email or text message. Anyone with the link can view the item copy unless you specify addresses with the emails flag. If you edit an item, your changes won't be shared until you share the item again. Note that file attachments and Document items cannot be shared. ## item template ### Subcommands {#item-template-subcommands} - [item template get](#item-template-get): Get an item template - [item template list](#item-template-list): Get a list of templates ## item template get Return a template for an item type. ``` op item template get [{ | - }] [flags] ``` ### Flags {#item-template-get-flags} ``` --file-mode filemode Set filemode for the output file. It is ignored without the --out-file flag. (default 0600) -f, --force Do not prompt for confirmation. -o, --out-file string Write the template to a file instead of stdout. ``` You can create a new item with a template. Run `op item create --help` for more information. Categories are: - API Credential - Bank Account - Credit Card - Database - Document - Driver License - Email Account - Identity - Login - Membership - Outdoor License - Passport - Password - Reward Program - Secure Note - Server - Social Security Number - Software License - Wireless Router ## item template list Lists available item type templates. ``` op item template list [flags] ``` Use `op item template get ` to get a template. --- ## 1Password CLI reference :::info Get started If you're new to 1Password CLI, [learn how to set it up and sign in to your account](/docs/cli/get-started/). ::: ## Command structure ``` op [command] ``` 1Password CLI uses a noun-verb command structure that groups commands by topic rather than by operation. The basic structure of a command starts with the 1Password program `op`, then the command name (noun), often followed by a subcommand (verb), then flags (which include additional information that gets passed to the command). For example, to retrieve a list of all the items in your Private vault: ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "item" }, { "badge": 2, "color": "tangerine", "lineNo": 1, "substr": "list" }, { "badge": 3, "color": "dahlia", "lineNo": 1, "substr": "--vault Private" }] op item list --vault Private ``` To get a list of all global commands and flags, run the following: ​ ```shell op --help ``` ## Command reference - [account](/docs/cli/reference/management-commands/account): Manage your locally configured 1Password accounts - [completion](/docs/cli/reference/commands/completion): Generate shell completion information - [connect](/docs/cli/reference/management-commands/connect): Manage Connect server instances and tokens in your 1Password account - [document](/docs/cli/reference/management-commands/document): Perform CRUD operations on Document items in your vaults - [environment](/docs/cli/reference/management-commands/environment): Manage your 1Password Environments and their variables (Beta) - [events-api](/docs/cli/reference/management-commands/events-api): Manage Events API integrations in your 1Password account - [group](/docs/cli/reference/management-commands/group): Manage the groups in your 1Password account - [inject](/docs/cli/reference/commands/inject): Inject secrets into a config file - [item](/docs/cli/reference/management-commands/item): Perform CRUD operations on the 1Password items in your vaults - [plugin](/docs/cli/reference/management-commands/plugin): Manage the shell plugins you use to authenticate third-party CLIs - [read](/docs/cli/reference/commands/read): Read a secret reference - [run](/docs/cli/reference/commands/run): Pass secrets as environment variables to a process - [service-account](/docs/cli/reference/management-commands/service-account): Manage service accounts - [signin](/docs/cli/reference/commands/signin): Sign in to a 1Password account - [signout](/docs/cli/reference/commands/signout): Sign out of a 1Password account - [update](/docs/cli/reference/commands/update): Check for and download updates - [user](/docs/cli/reference/management-commands/user): Manage users within this 1Password account - [vault](/docs/cli/reference/management-commands/vault): Manage permissions and perform CRUD operations on your 1Password vaults - [whoami](/docs/cli/reference/commands/whoami): Get information about a signed-in account ## Global flags ``` --account string Select the account to execute the command by account shorthand, sign-in address, account ID, or user ID. For a list of available accounts, run 'op account list'. Can be set as the OP_ACCOUNT environment variable. --cache Store and use cached information. Caching is enabled by default on UNIX-like systems. Caching is not available on Windows. Options: true, false. Can also be set with the OP_CACHE environment variable. (default true) --config directory Use this configuration directory. --debug Enable debug mode. Can also be enabled by setting the OP_DEBUG environment variable to true. --encoding type Use this character encoding type. Default: UTF-8. Supported: SHIFT_JIS, gbk. --format string Use this output format. Can be 'human-readable' or 'json'. Can be set as the OP_FORMAT environment variable. (default "human-readable") -h, --help Get help for op. --iso-timestamps Format timestamps according to ISO 8601 / RFC 3339. Can be set as the OP_ISO_TIMESTAMPS environment variable. --no-color Print output without color. --session token Authenticate with this session token. 1Password CLI outputs session tokens for successful `op signin` commands when 1Password app integration is not enabled. ``` ## Unique identifiers (IDs) When you retrieve information about an object using the `get` and `list` subcommands, you'll see a string of 26 numbers and letters that make up the object's unique identifier (ID). You can use names or IDs in commands that take any [account](/docs/cli/reference/management-commands/account#account-get), [user](/docs/cli/reference/management-commands/user#user-get), [vault](/docs/cli/reference/management-commands/vault#vault-get), or [item](/docs/cli/reference/management-commands/item#item-get) as an argument. IDs are the most stable way to reference an item. An item's ID only changes when you move the item to a different vault. Commands provided with an ID are also faster and more efficient. You can get information about an item, including the item's ID and the ID for the vault where it's stored, with [`op item get`](/docs/cli/reference/management-commands/item#item-get). ```shell op item get Netflix # code-result ID: t2Vz6kMDjByzEAcq6peKnHL4k3 Title: Netflix Vault: Private (sdfsdf7werjgdf8gdfgjdfgkj) Created: 6 months ago Updated: 1 month ago by Wendy Appleseed Favorite: false Version: 1 Category: LOGIN ``` To only fetch the item ID, use the same command with the format set to JSON, then use [jq ](https://jqlang.github.io/jq/) to parse the output. ```shell op item get Netflix --format json | jq .id #code-result "t2Vz6kMDjByzEAcq6peKnHL4k3" ``` To get the IDs for all vaults in an account: ```shell op vault list #code-result ID NAME cfqtakqiutfhiewomztljx4woy Development rr3ggvrlr6opoete23q7c22ahi Personal 2gq6v6vzorl7jfxdurns4hl66e Work ``` ## Shell completion You can add shell completion so that 1Password CLI automatically completes your commands. With shell completion enabled, start typing an `op` command, then press Tab to see the available commands and options. **Bash:** To enable shell completion with Bash: 1. Install the bash-completion package 2. Add this line to your `.bashrc` file: ``` source <(op completion bash) ``` **Zsh:** To enable shell completion with Zsh, add this line to your `.zshrc` file: ``` eval "$(op completion zsh)"; compdef _op op ``` **fish:** To enable shell completion with fish, add this to your `.fish` file: ``` op completion fish | source ``` **PowerShell:** To enable shell completion with PowerShell, add this to your `.ps1` file: ```powershell op completion powershell | Out-String | Invoke-Expression ``` You'll need to enable script execution in PowerShell to start using shell completion. To do that, start a PowerShell window as an administrator and enter: ```powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned ``` ## Cache item and vault information 1Password CLI can use its daemon process to cache items, vault information, and the keys to access information in an account. The daemon stores encrypted information in memory using the same encryption methods as on 1Password.com. It can read the information to pass to 1Password CLI, but can’t decrypt it. On UNIX-like systems, caching between commands is enabled by default. This helps maximize performance and reduce the number of API calls. If you use 1Password CLI in an environment where caching is not possible, you can turn it off by appending the `--cache=false` flag to your commands, or by setting the `OP_CACHE` environment variable to false. Caching is not currently available on Windows. ## Alternative character encoding By default, 1Password CLI processes input and output with UTF-8 encoding. You can use an alternative character encoding with the `--encoding` option. Supported alternative character encoding types: - `gbk` - `shift-jis` ## Parse JSON output with jq You can use the `--format` flag or the `OP_FORMAT` environment variable to set your 1Password CLI command output to `json`. To parse JSON output, we recommend using the command-line tool [jq. ](https://jqlang.github.io/jq/) For example, to use jq to retrieve a secret reference for the password saved on an item named `GitHub`: ```shell op item get GitHub --format json --fields password | jq .reference #code-result "op://development/GitHub/password" ``` ## Beta builds To download 1Password CLI beta builds, navigate to [the 1Password CLI downloads page](https://app-updates.agilebits.com/product_history/CLI2) and select **Show betas**. On Linux, you can switch the channel from "stable" to "beta" when adding the 1Password repository in your package manager. ## Example commands ### Items To get information about an item: ```shell op item get ``` You'll see the item's [ID](#unique-identifiers-ids), title, vault, when it was created, when it was last modified, the item's version, if it's marked as a favorite, the type of item it is, and the item's fields. If an item name includes spaces or special characters, enclose it in quotes. For example: ```shell op item get "work email" #code-result ID: a5w3is43ohs25qonzajrqaqx4q Title: work email Vault: Work (2gq6v6vzorl7jfxdurns4hl66e) Created: 6 years ago Updated: 9 months ago by Wendy Appleseed Favorite: true Version: 1 Category: LOGIN Fields: username: wendy.c.appleseed@agilebits.com password: NLuXcEtg27JMjGmiBHXZMGCgce URLs: website: https://www.gmail.com (primary) ``` To use `op item get` to retrieve specific fields, include the `--fields` flag followed by a comma-separated list, with the prefix `label=` before each field name. For example, to only retrieve the username and password for the item `work email`: ```shell op item get "work email" --fields label=username,label=password #code-result wendy.c.appleseed@agilebits.com,NLuXcEtg27JMjGmiBHXZMGCgce ``` Learn more about working with [items](/docs/cli/reference/management-commands/item/). ### Users and groups To get details about a user: ```shell op user get "Wendy Appleseed" #code-result ID: SPRXJFTDHTA2DDTPE5F7DA64RQ Name: Wendy Appleseed Email: wendy.c.appleseed@agilebits.com State: ACTIVE Type: MEMBER Created: 6 years ago Updated: 4 months ago Last Authentication: 1 month ago ``` To list the users who belong to a group: ``` op group user list "Provision Managers" #code-result ID NAME EMAIL STATE TYPE ROLE 7YEOODASGJE6VAEIOHYWGP33II Wendy Appleseed wendy.c.appleseed@agilebits.com ACTIVE MEMBER UKCYFVOJSFEXLKKZREG7M2MZWM Johnny Appleseed johnny.appleseed@agilebits.com RECOVERY_STARTED MEMBER ``` Learn more about working with [users](/docs/cli/reference/management-commands/user/) and [groups](/docs/cli/reference/management-commands/group/). ### Vaults To create a new vault named `Test`: ```shell op vault create Test ``` To get details about an existing vault: ```shell op vault get Work #code-result ID: jAeq2tfunmifZfG4WkuWvsaGGj Name: Work Type: USER_CREATED Attribute version: 3 Content version: 241 Items: 25 Created: 1 year ago Updated: 1 month ago ``` To list the vaults in an account: ```shell op vault list #code-result ID NAME vw8qjYEvsdCcZoULJRCqopy7Rv Development 2RNjh43dpHB9sDqZXEHiiw7zTe Personal cGxbZbV2pxKBmVJe9oWja4K8km Work ``` Learn more about working with [vaults](/docs/cli/reference/management-commands/vault/). ### Secrets To insert a secret into an environment variable, config file, or script without putting the plaintext secret in code, use a [secret reference](/docs/cli/secret-reference-syntax/) that specifies where the secret is stored in your 1Password account: ``` op://vault-name/item-name/[section-name/]field-name ``` Then, you can use [`op read`](/docs/cli/reference/commands/read/), [`op run`](/docs/cli/reference/commands/run/), or [`op inject`](/docs/cli/reference/commands/inject/) to replace the secret reference with the actual secret at runtime. To resolve a secret reference and confirm it outputs correctly: ```shell op read "op://Work/work email/username" #code-result wendy.c.appleseed@agilebits.com ``` Learn more about [loading secrets](/docs/cli/secret-references/). ## Get help For help with any command, use the `--help` option: ``` op [subcommand] --help ``` --- ## plugin | 1Password CLI # plugin Manage your shell plugin configurations. You can use shell plugins to securely authenticate third-party CLIs with 1Password, rather than storing your CLI credentials in plaintext. After you configure a plugin, 1Password CLI will prompt you to authenticate the third-party CLI with your fingerprint or other system authentication option. [Learn more about shell plugins.](/docs/cli/shell-plugins) ### Subcommands {#subcommands} - [plugin clear](#plugin-clear): Clear shell plugin configuration - [plugin init](#plugin-init): Configure a shell plugin - [plugin inspect](#plugin-inspect): Inspect your existing shell plugin configurations - [plugin list](#plugin-list): List all available shell plugins - [plugin run](#plugin-run): Provision credentials from 1Password and run this command ## plugin clear Clear an existing shell plugin configuration. ```shell op plugin clear [flags] ``` ### Flags {#plugin-clear-flags} ``` --all Clear all configurations for this plugin that apply to this directory and/or terminal session, including the global default. -f, --force Apply immediately without asking for confirmation. ``` You can clear one configuration at a time, in this order of precedence: - Terminal session default - Directory default, from the current directory to `$HOME` - Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear aws` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear aws --all`. ## plugin init Choose a shell plugin to install and configure your default credentials. Bash, Zsh, and fish shells are supported. ```shell op plugin init [ ] [flags] ``` Shell plugins require the [1Password desktop app integration](/docs/cli/shell-plugins/). To see all available plugins, run `op plugin list`. #### Configure your default credentials 1Password CLI prompts you to select or import the credentials you want to use with the third-party CLI, then returns a command to source your `plugins.sh` file and make the plugin alias usable. To use the plugin beyond the current terminal session, make sure to add the source command to your RC file or shell profile (e.g. `~/.bashrc`, `~/.zshrc`, `~/.config/fish/config.fish`). For example: ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` #### Configuration options You can choose whether 1Password CLI remembers your configuration. With any option, your credentials never leave your 1Password account. - "Prompt me for each new terminal session" only configures the credentials for the current terminal session. Once you exit the terminal, your default is removed. - "Use automatically when in this directory or subdirectories" makes your credentials the default in the current directory and all its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. - "Use as global default on my system" sets the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## plugin inspect Inspect your existing shell plugin configurations. ```shell op plugin inspect [ ] [flags] ``` You can run `op plugin inspect` to select a plugin from the list of all available plugins, or `op plugin inspect ` to inspect a specific plugin. 1Password CLI returns a list of the credentials you've configured to use with the plugin and their default scopes, as well as configured alias details. ## plugin list Lists all available shell plugins, their usage, name, and required fields. ```shell op plugin list [flags] ``` To get started with a shell plugin, run `op plugin init `. ## plugin run Provision credentials from 1Password and run this command. ```shell op plugin run ... [flags] ``` `op plugin run` passes your credentials saved in 1Password to the underlying CLI and runs the provided command. If you haven't configured your default credentials, 1Password CLI will prompt you to select an item that contains your credentials. After this, you will be automagically authenticated with this CLI, and your selection will be recorded for future calls to this plugin in the current terminal session. To configure a default credential, see `op plugin init --help`. --- ## read | 1Password CLI # read Read the value of the field in 1Password specified by a secret reference. [Learn more about secret references and query parameters.](/docs/cli/secret-reference-syntax/) ``` op read [flags] ``` ### Flags {#flags} ``` --file-mode filemode Set filemode for the output file. It is ignored without the --out-file flag. (default 0600) -f, --force Do not prompt for confirmation. -n, --no-newline Do not print a new line after the secret. -o, --out-file string Write the secret to a file instead of stdout. ``` ### Examples {#examples} Print the secret saved in the field `password`, on the item `db`, in the vault `app-prod`: ```shell op read op://app-prod/db/password ``` Use a secret reference with a query parameter to retrieve a one-time password: ```shell op read "op://app-prod/db/one-time password?attribute=otp" ``` Use a secret reference with a query parameter to get an SSH key's private key in the OpenSSH format: ```shell op read "op://app-prod/ssh key/private key?ssh-format=openssh" ``` Save the SSH key found on the item `ssh` in the `server` vault as a new file `key.pem` on your computer: ```shell op read --out-file ./key.pem op://app-prod/server/ssh/key.pem ``` Use `op read` in a command with secret references in place of plaintext secrets: ```shell docker login -u $(op read op://prod/docker/username) -p $(op read op://prod/docker/password) ``` --- ## run | 1Password CLI # run Pass secrets as environment variables to an application or script. ``` op run -- ... [flags] ``` ### Flags {#flags} ``` --env-file stringArray Enable Dotenv integration with specific Dotenv files to parse. For example: --env-file=.env. --no-masking Disable masking of secrets on stdout and stderr. ``` Use `op run` to securely load project secrets from 1Password, then run a provided command in a subprocess with the secrets made available as environment variables only for the duration of the subprocess. To limit which 1Password items processes in your authorized terminal session can access, make sure to authenticate 1Password CLI with a service account that only has access to the required secrets. You can scope service accounts to specific vaults and 1Password Environments. [Learn more about service accounts.](/docs/service-accounts/) [Learn more about loading secrets with `op run`.](/docs/cli/secrets-environment-variables) #### Load secrets using secret references `op run` can scan environment variables and files for secret references, then load the provided command with the referenced secrets made available as environment variables. Secret references are URIs that point to the ID or name of the vault, item, section, and field where a secret is stored in 1Password. You can export environment variables to secret references on the command line or using an .env file. Secrets printed to stdout or stderr are concealed by default. Include the `--no-masking` flag to turn off masking. When referencing an environment variable assigned to a secret reference within a command, `op run` must replace the reference with the actual secret value before the variable expands. To make sure this order of operations is followed, run the command that expands the variable in a subshell. #### Load variables from environments (Beta) :::note The `--environments` flag is available in [the latest beta build of 1Password CLI](/docs/cli/reference#beta-builds), version `2.33.0-beta.02` or later. ::: Use `op run` with the `--environments` flag and an Environment's ID to load variables from a 1Password Environment. To find an Environment's ID, open the 1Password app, navigate to Developer > View Environments > then select View environment > Manage environment > Copy environment ID. Load variables from a 1Password Environment: ```shell op run --environment -- printenv ``` #### Environment variable precedence If the same environment variable name exists in multiple sources, the source with higher precedence takes effect. Precedence from highest to lowest: 1. 1Password Environments (--environment) 2. Environment files (--env-file) 3. Shell environment variables If the same environment variable name exists in multiple environment files, the last environment file takes precedence. If the same environment variable name exists in multiple 1Password Environments, the last Environment specified takes precedence. ### Examples {#examples} Print secret value: ``` export DB_PASSWORD="op://app-prod/db/password" ``` ``` op run -- printenv DB_PASSWORD ``` ``` op run --no-masking -- printenv DB_PASSWORD fX6nWkhANeyGE27SQGhYQ ``` Specify an environment file and use it: ``` echo "DB_PASSWORD=op://app-dev/db/password" > .env ``` ``` op run --env-file="./.env" -- printenv DB_PASSWORD password ``` Use variables in secret references to switch between different sets of secrets for different environments: ``` cat .env DB_USERNAME = op://$APP_ENV/db/username DB_PASSWORD = op://$APP_ENV/db/password ``` ``` export APP_ENV="dev" op run --env-file="./.env" -- printenv DB_PASSWORD dev ``` ``` export APP_ENV="prod" op run --env-file="./.env" -- printenv DB_PASSWORD prod ``` --- ## service-account | 1Password CLI # service-account Manage service accounts. ### Subcommands {#subcommands} - [service-account create](#service-account-create): Create a service account - [service-account ratelimit](#service-account-ratelimit): Retrieve rate limit usage for a service account ## service-account create Create a service account to gain programmatic access to your secrets using 1Password CLI. ```shell op service-account create [flags] ``` ### Flags {#service-account-create-flags} ``` --can-create-vaults Allow the service account to create new vaults. --expires-in duration Set how long the service account is valid for in (s)econds, (m)inutes, (h)ours, (d)ays, or (w)eeks. --raw Only return the service account token. --vault stringArray Give access to this vault with a set of permissions. Has syntax :[,] ``` You can specify the vaults the service account can access, as well as the permissions it will have for each vault using the `--vault` flag. The syntax looks like this: ```shell --vault :, ``` The permissions can be one of the following: - `read_items` - `write_items` (requires `read_items`) - `share_items` (requires `read_items`) If no permissions are specified, it will default to `read_items`. You can set an expiry to a service account using the `--expires-in` flag. 1Password CLI only returns the service account token once. Save the token in 1Password immediately to avoid losing it. Treat this token like a password, and don't store it in plaintext. :::note You can't grant a service account access to your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault. ::: ### Examples {#service-account-create-examples} Create a new service account: ```shell op service-account create my-service-account --vault Dev:read_items --vault Test:read_items,write_items ``` Create a service account with an expiry: ```shell op service-account create my-service-account --expires-in=24h ``` Create a service account that can create new vaults: ```shell op service-account create my-service-account --can-create-vaults ``` ## service-account ratelimit Retrieve hourly and daily rate limit usage for a service account. ```shell op service-account ratelimit [{ | }] [flags] ``` --- ## signin | 1Password CLI # signin Sign in to 1Password CLI using the 1Password desktop app. ```shell op signin [flags] ``` ### Flags {#flags} ``` -f, --force Ignore warnings and print raw output from this command. --raw Only return the session token. ``` To turn on the 1Password app integration: 1. Open the 1Password app. 2. Navigate to **Settings** > **Security** and turn on Touch ID, Windows Hello, or a Linux system authentication option. 3. Navigate to **Developer** > **Settings** and select **Integrate with 1Password CLI**. [Learn more about the app integration.](/docs/cli/app-integration/) If you add multiple 1Password accounts to the 1Password app, 1Password CLI determines which to use in this order: 1. The account specified with the `--account` flag. 2. The account specified by the `OP_ACCOUNT` environment variable. 3. The account you most recently signed in to with `op signin` in any terminal window. `op signin` is idempotent. It only prompts for authentication if you aren't already authenticated. ### Examples {#examples} Sign in and set the environment variable in one step: ```shell eval $(op signin --account acme.1password.com) ``` --- ## signout | 1Password CLI # signout Sign out of a 1Password account. ``` op signout [flags] ``` ### Flags {#flags} ``` --all Sign out of all signed-in accounts. --forget Remove the details for a 1Password account from this device. ``` Signs out of the most recently used account by default. --- ## Update to the latest version of 1Password CLI To make sure you're up to date with the latest features and security improvements, always use the latest version of 1Password CLI. To check what version you currently have installed, use `op --version`. ## Download the latest version There are two ways you can download the latest version for your platform and architecture: - Visit our [release page](https://app-updates.agilebits.com/product_history/CLI2) and download the latest version of 1Password CLI. - Use `op update` to download the latest version from the command line. Set the `--directory` flag to choose where to download the installer (defaults to `~/Downloads`) and confirm the download. You can use `op update` without signing in. After downloading the appropriate installer, follow the [installation instructions](/docs/cli/get-started#step-1-install-1password-cli) to finish the update. ## Update with a package manager If you installed 1Password CLI with a package manager, use the following commands to update your installation. **Mac:** **Brew** ```shell brew upgrade --cask 1password-cli ``` **Linux:** **Apt:** ```shell sudo apt update && sudo apt install 1password-cli ``` **Yum:** ```shell sudo dnf check-update -y 1password-cli && sudo dnf install 1password-cli ``` **Alpine:** ```shell apk add --update-cache 1password-cli ``` --- ## update | 1Password CLI # update Check for updates to `op` and download an updated version, if available. ``` op update [flags] ``` ### Flags {#flags} ``` --directory path Download the update to this path. --channel string Look for updates from a specific channel. allowed: stable, beta ``` --- ## user | 1Password CLI # user ### Subcommands {#subcommands} - [user confirm](#user-confirm): Confirm a user - [user delete](#user-delete): Remove a user and all their data from the account - [user edit](#user-edit): Edit a user's name or Travel Mode status - [user get](#user-get): Get details about a user - [user list](#user-list): List users - [user provision](#user-provision): Provision a user in the authenticated account - [user reactivate](#user-reactivate): Reactivate a suspended user - [user recovery](#user-recovery): Manage user recovery in your 1Password account - [user suspend](#user-suspend): Suspend a user ## user confirm Specify the user by their e-mail address, name, or ID. ```shell op user confirm [{ | | | - }] [flags] ``` ### Flags {#user-confirm-flags} ``` --all Confirm all unconfirmed users. ``` Specify the user by their e-mail address, name, or ID. ### Examples {#user-confirm-examples} Confirm a user by specifying their name: ```shell op user confirm "Wendy Appleseed" ``` Confirm a user by specifying their email: ```shell op user confirm "wendy.appleseed@example.com" ``` ## user delete Remove a user and all their data from the account. ```shell op user delete [{ | | | - }] [flags] ``` Specify the user by their e-mail address, name, or ID. ## user edit Change a user's name or Travel Mode status. ```shell op user edit [{ | | | - }] [flags] ``` ### Flags {#user-edit-flags} ``` --name string Set the user's name. --travel-mode on|off Turn Travel Mode on or off for the user. (default off) ``` Specify the user by their e-mail address, name, or ID. ## user get Get details about a user. ```shell op user get [{ | | | --me | - }] [flags] ``` ### Flags {#user-get-flags} ``` --fingerprint Get the user's public key fingerprint. --me Get the authenticated user's details. --public-key Get the user's public key. ``` Specify the user by their e-mail address, name, or ID. #### Use standard input to specify objects If you enter a hyphen (`-`) instead of a single object for this command, the tool will read object specifiers from standard input (stdin). Separate each specifier with a new line. For more information about how to specify objects, run `op help`. You can also pass the command a list or array of JSON objects. The tool will get an item for any object that has an ID, ignoring line breaks. This is useful for passing information from one `op` command to another. ### Examples {#user-get-examples} Look up a user by name: ```shell op user get "Wendy Appleseed" ``` Look up a user by e-mail: ```shell op user get wendy.appleseed@example.com ``` Get details for all users: ```shell op user list --format=json | op user get - ``` Get the public key for all users in a group: ```shell op user list --group "Frontend Developers" --format=json | op user get - --publickey ``` Get details for all users who have access to a vault: ```shell op user list --vault Staging --format=json | op user get - ``` ## user list List users. ```shell op user list [flags] ``` ### Flags {#user-list-flags} ``` --group group List users who belong to a group. --vault vault List users who have direct access to vault. ``` Returns all users in an account by default. Use flags to filter results. When you use the `--group` option, the output includes the user's role in the group. ### Examples {#user-list-examples} Get details for all users: ```shell op user list --format=json | op user get - ``` Get the public key for all users in a group: ```shell op user list --group "Frontend Developers" --format=json | op user get - --publickey ``` Get details for all users who have access to a vault: ```shell op user list --vault Staging --format=json | op user get - ``` ## user provision Provision a user in the authenticated account. ```shell op user provision [flags] ``` ### Flags {#user-provision-flags} ``` --email string Provide the user's email address. --language string Provide the user's account language. (default "en") --name string Provide the user's name. ``` Provisioned users will receive an invitation email to join the 1Password account. Once a user accepts an invitation, an admin must confirm them on 1Password.com or using the `op user confirm` command. Invited users will not be considered for billing until they accept their invitation. ### Examples {#user-provision-examples} Invite a user by specifying their e-mail address and name: ```shell op user provision --name "Wendy Appleseed" --email "wendy.appleseed@example.com" ``` ## user reactivate Reactivate a suspended user. ```shell op user reactivate [{ | | | - }] [flags] ``` A user may be specified by their e-mail address, name, or ID. ## user recovery ### Subcommands {#user-recovery-subcommands} - [user recovery begin](#user-recovery-begin): Begin recovery for users in your 1Password account ## user recovery begin Begin recovery for users in your 1Password account: ```shell op user recovery begin [ { | | } ] [flags] ``` ### Examples {#user-recovery-begin-examples} Begin recovery for multiple users by UUID: ```shell op user recovery begin ZMAE4RTRONHN7LGELNYYO373KM WHPOFIMMYFFITBVTOTZUR3R324 ``` ## user suspend Suspend a user. ```shell op user suspend [{ | | | - }] [flags] ``` ### Flags {#user-suspend-flags} ``` --deauthorize-devices-after duration Deauthorize the user's devices after a time (rounded down to seconds). ``` Specify the user by their e-mail address, name, or ID. A suspended user will immediately be logged out of all devices and will not be able to log in or access any data. Users in a suspended state are not considered in billing. You can reactivate a suspended user with the `op user reactivate` command. --- ## vault | 1Password CLI # vault Manage permissions and perform CRUD operations on your 1Password vaults. ### Subcommands {#subcommands} - [vault create](#vault-create): Create a new vault - [vault delete](#vault-delete): Remove a vault - [vault edit](#vault-edit): Edit a vault's name, description, icon, or Travel Mode status - [vault get](#vault-get): Get details about a vault - [vault group](#vault-group): Manage group vault access - [vault list](#vault-list): List all vaults in the account - [vault user](#vault-user): Manage user vault access ## vault create Create a new vault ``` op vault create [flags] ``` ### Flags {#vault-create-flags} ``` --allow-admins-to-manage true|false Set whether administrators can manage the vault. If not provided, the default policy for the account applies. --description description Set the vault's description. --icon string Set the vault icon. ``` Valid icon keywords are: airplane, application, art-supplies, bankers-box, brown-briefcase, brown-gate, buildings, cabin, castle, circle-of-dots, coffee, color-wheel, curtained-window, document, doughnut, fence, galaxy, gears, globe, green-backpack, green-gem, handshake, heart-with-monitor, house, id-card, jet, large-ship, luggage, plant, porthole, puzzle, rainbow, record, round-door, sandals, scales, screwdriver, shop, tall-window, treasure-chest, vault-door, vehicle, wallet, wrench ## vault delete Remove a vault. Specify the vault to delete by name or ID. ``` op vault delete [{ | | - }] [flags] ``` A vault may be specified by name or ID. ## vault edit Edit a vault's name, description, icon, or Travel Mode status. Specify the vault by name or ID. ``` op vault edit [{ | | - }] [flags] ``` ### Flags {#vault-edit-flags} ``` --description description Change the vault's description. --icon icon Change the vault's icon. --name name Change the vault's name. --travel-mode on|off Turn Travel Mode on or off for the vault. Only vaults with Travel Mode enabled are accessible while a user has Travel Mode turned on. (default off) ``` A vault may be specified by name or ID. Valid icon keywords are: airplane, application, art-supplies, bankers-box, brown-briefcase, brown-gate, buildings, cabin, castle, circle-of-dots, coffee, color-wheel, curtained-window, document, doughnut, fence, galaxy, gears, globe, green-backpack, green-gem, handshake, heart-with-monitor, house, id-card, jet, large-ship, luggage, plant, porthole, puzzle, rainbow, record, round-door, sandals, scales, screwdriver, shop, tall-window, treasure-chest, vault-door, vehicle, wallet, wrench ## vault get Get details about a vault. Specify the vault by name or ID. ``` op vault get [{ | | - }] [flags] ``` A vault may be specified by name or ID. #### Use standard input to specify objects If you enter a hyphen (`-`) instead of a single object for this command, the tool will read object specifiers from standard input (stdin). Separate each specifier with a new line. For more information about how to specify objects, run `op help`. You can also pass the command a list or array of JSON objects. The tool will get an item for any object that has an ID, ignoring line breaks. This is useful for passing information from one `op` command to another. ### Examples {#vault-get-examples} Get details for all vaults: ``` op vault list --format=json | op vault get - ``` Get details for the vaults that a group has access to: ``` op vault list --group security --format=json | op vault get - ``` ## vault group ### Subcommands {#vault-group-subcommands} - [vault group grant](#vault-group-grant): Grant a group permissions to a vault - [vault group list](#vault-group-list): List all the groups that have access to the given vault - [vault group revoke](#vault-group-revoke): Revoke a portion or the entire access of a group to a vault ## vault group grant Grant a group permissions in a vault. ``` op vault group grant [flags] ``` ### Flags {#vault-group-grant-flags} ``` --group group The group to receive access. --no-input input Do not prompt for input on interactive terminal. --permissions permissions The permissions to grant to the group. --vault vault The vault to grant group permissions to. ``` Permissions are specified in a comma separated list such as: ``` view_items,view_and_copy_passwords,edit_items ``` 1Password Teams includes three permissions: ``` allow_viewing, allow_editing, allow_managing ``` 1Password Business includes the permissions above as well as more granular options: allow_viewing ``` view_items, view_and_copy_passwords, view_item_history ``` allow_editing ``` create_items, edit_items, archive_items, delete_items, import_items, export_items, copy_and_share_items, print_items ``` allow_managing ``` manage_vault ``` When granting or revoking permissions, some permissions require dependent permissions to be granted or revoked alongside them. [Learn more about managing vault permissions.](/docs/cli/vault-permissions/) ### Examples {#vault-group-grant-examples} Grant a group certain permissions in a vault with a business account: ``` op vault group grant --vault VAULT --group GROUP \ --permissions view_items,create_items,allow_viewing ``` ``` op vault group grant --vault VAULT --group GROUP \ --permissions allow_viewing,export_items ``` Grant a group certain permissions in a vault with a team account: ``` op vault group grant --vault VAULT --group GROUP \ --permissions allow_viewing,allow_editing ``` ## vault group list List all the groups that have access to the given vault. ``` op vault group list [{ | - }] [flags] ``` ## vault group revoke Revoke a group's permissions in a vault, in part or in full. ``` op vault group revoke [flags] ``` ### Flags {#vault-group-revoke-flags} ``` --group group The group to revoke access from. --no-input input Do not prompt for input on interactive terminal. --permissions permissions The permissions to revoke from the group. --vault vault The vault to revoke access to. ``` Not specifying any permissions revokes the group's access to the vault. Removing all existing permissions also revokes the group’s access to the vault. Permissions are specified in a comma separated list such as: ``` view_items,view_and_copy_passwords,edit_items ``` 1Password Teams includes three permissions: ``` allow_viewing, allow_editing, allow_managing ``` 1Password Business includes the permissions above as well as more granular options: allow_viewing ``` view_items, view_and_copy_passwords, view_item_history ``` allow_editing ``` create_items, edit_items, archive_items, delete_items, import_items, export_items, copy_and_share_items, print_items ``` allow_managing ``` manage_vault ``` When granting or revoking permissions, some permissions require dependent permissions to be granted or revoked alongside them. [Learn more about managing vault permissions.](/docs/cli/vault-permissions/) ### Examples {#vault-group-revoke-examples} Remove a group from a vault: ``` op vault group revoke --vault VAULT --group GROUP ``` Revoke certain permissions from a group in a vault with a business account: ``` op vault group revoke --vault VAULT --group GROUP \ --permissions view_items,create_items,allow_editing ``` Revoke certain permissions from a group in a vault with a team account: ``` op vault group revoke --vault VAULT --group GROUP \ --permissions allow_viewing,allow_editing ``` ## vault list List vaults. ``` op vault list [flags] ``` ### Flags {#vault-list-flags} ``` --group string List vaults a group has access to. --permission permissions List only vaults that the specified user/group has this permission for. --user string List vaults that a given user has access to. ``` By default, returns all vaults the current user has read access to. ### Examples {#vault-list-examples} Get details for all vaults: ``` op vault list --format=json | op vault get - ``` Get details for vaults that a group has access to: ``` op vault list --group Security --format=json | op vault get - ``` Get details for vaults that a user has access to: ``` op vault list --user wendy_appleseed@1password.com --format=json | op vault get - ``` Only list vaults for which the user/group has a specific set of permissions: ``` op vault list --user wendy_appleseed@1password.com --permission manage_vault ``` ## vault user ### Subcommands {#vault-user-subcommands} - [vault user grant](#vault-user-grant): Grant a user access to a vault - [vault user list](#vault-user-list): List all users with access to the vault and their permissions - [vault user revoke](#vault-user-revoke): Revoke a portion or the entire access of a user to a vault ## vault user grant Grant a user permissions in a vault. ``` op vault user grant [flags] ``` ### Flags {#vault-user-grant-flags} ``` --no-input input Do not prompt for input on interactive terminal. --permissions permissions The permissions to grant to the user. --user user The user to receive access. --vault vault The vault to grant access to. ``` Permissions are specified in a comma separated list such as: ``` view_items,view_and_copy_passwords,edit_items ``` 1Password Teams and 1Password Families include three permissions: ``` allow_viewing, allow_editing, allow_managing ``` 1Password Business includes the permissions above as well as more granular options: allow_viewing ``` view_items, view_and_copy_passwords, view_item_history ``` allow_editing ``` create_items, edit_items, archive_items, delete_items, import_items, export_items, copy_and_share_items, print_items ``` allow_managing ``` manage_vault ``` When granting or revoking permissions, some permissions require dependent permissions to be granted or revoked alongside them. [Learn more about managing vault permissions.](/docs/cli/vault-permissions/) ### Examples {#vault-user-grant-examples} Grant a user certain permissions in a vault with a business account: ``` op vault user grant --vault VAULT --user USER \ --permissions view_items,create_items,allow_viewing ``` ``` op vault user grant --vault VAULT --user USER \ --permissions allow_viewing,export_items ``` Grant a user certain permissions in a vault with a team account: ``` op vault user grant --vault VAULT --user USER \ --permissions allow_viewing,allow_editing ``` ## vault user list List all users with access to the vault and their permissions. ``` op vault user list [flags] ``` ## vault user revoke Revoke a user's permissions in a vault, in part or in full. ``` op vault user revoke [flags] ``` ### Flags {#vault-user-revoke-flags} ``` --no-input input Do not prompt for input on interactive terminal. --permissions permissions The permissions to revoke from the user. --user user The user to revoke access from. --vault vault The vault to revoke access to. ``` Not specifying any permissions revokes the user's access to the vault. Removing all existing permissions also revokes the user’s access to the vault. Permissions are specified in a comma separated list such as: ``` view_items,view_and_copy_passwords,edit_items ``` 1Password Teams and 1Password Families include three permissions: ``` allow_viewing, allow_editing, allow_managing ``` 1Password Business includes the permissions above as well as more granular options: allow_viewing ``` view_items, view_and_copy_passwords, view_item_history ``` allow_editing ``` create_items, edit_items, archive_items, delete_items, import_items, export_items, copy_and_share_items, print_items ``` allow_managing ``` manage_vault ``` When granting or revoking permissions, some permissions require dependent permissions to be granted or revoked alongside them. [Learn more about managing vault permissions.](/docs/cli/vault-permissions/) ### Examples {#vault-user-revoke-examples} Remove a user from a vault: ``` op vault user revoke --vault VAULT --user USER ``` Revoke certain permissions from a user in a vault with a business account: ``` op vault user revoke --vault VAULT --user USER \ --permissions view_items,create_items,allow_editing ``` Revoke certain permissions from a user in a vault with a team account: ``` op vault user revoke --vault VAULT --user USER \ --permissions allow_viewing,allow_editing ``` --- ## whoami | 1Password CLI # whoami Get information about a signed-in account. ``` op whoami [flags] ``` Returns the currently active account or service account. The command returns an error if no accounts are currently authenticated. Get information about a specific account with the `--account ` flag. --- ## 1Password app integration security ## Security model [Integrating 1Password CLI with the 1Password app](/docs/cli/app-integration/) allows you to use accounts you've added to the 1Password desktop app with 1Password CLI. Every time you use 1Password CLI in a new terminal window or tab, you'll be asked to authorize with biometrics. This authorization establishes a 10-minute session that automatically refreshes on each use. 1Password accounts can only be accessed through 1Password CLI after the user provides explicit biometric authorization and authorization is limited to an single account at a time. The user is shown a prompt containing the 1Password account display name (for example, `AgileBits` or `Wendy Appleseed's Family`) and the process being authorized (for example, `iTerm2` or `Terminal`). The user must confirm the prompt for 1Password CLI to be granted access to the requested account details. Authorizing use of 1Password CLI while the 1Password app is locked will result in the 1Password app unlocking. When the 1Password app is locked, all prior authorization is revoked. Any new invocation of 1Password CLI will require new authorization. If a process is running at the moment authorization is revoked or expires, it will be able to finish its task and exit. ## Authorization model Authorization in 1Password CLI occurs on a per-account basis. If you sign in to multiple accounts, each account must be authorized separately. Authorization expires after 10 minutes of inactivity in the terminal session. There's a hard limit of 12 hours, after which you must reauthorize. Each time you use a 1Password CLI command in a new terminal window or tab, you'll need to authorize your account again: - On macOS and Linux, authorization is confined to a terminal session but extends to sub-shell processes in that window. - On Windows, commands executed in a sub-shell require separate authorization. ## Accepted risks - A user or application with root/administrator level privileges on the same system may be able to circumvent one or more security measures and could obtain access to 1Password accounts through 1Password CLI without authorization if (and only if) the 1Password app is unlocked. - Applications that are granted accessibility permissions on macOS may be able to circumvent the authorization prompt. ## Technical design ### Session credentials Session credentials are used to identify the terminal window or application where 1Password CLI is invoked. The goal is to restrict the granted authorization to a single terminal. If a user authorizes `account X` in one terminal window, using `account y` in another terminal window requires another approval from the user. These credentials don't consist of any sensitive or secret information. **Mac:** The session credential for macOS is an ID that's based on the current `tty`, plus the start time. This way every session credential is unique, even after an ID gets reused. **Linux:** The session credential for Linux is an ID that's based on the current `tty`, plus the start time. This way every session credential is unique, even after an ID gets reused. **Windows:** The session credential for Windows is an ID that's based on the PID of the process that invokes 1Password CLI, plus the start time. This way every session credential is unique, even after an ID gets reused. ### How does 1Password CLI communicate with the 1Password app? 1Password CLI uses inter-process communication to reach out to the 1Password app to obtain access to the accounts stored in the app. **Mac:** The `NSXPCConnection` XPC API is used for IPC. The 1Password app sets up a service (`1Password Browser Helper`) that acts as an XPC server. Both 1Password CLI and the 1Password app connect to this server. Authenticity of both is confirmed by verifying the code signature. The `1Password Browser Helper` acts as a message relay between the 1Password app and 1Password CLI. **Linux:** 1Password CLI connects to a Unix socket opened by the 1Password app. The socket is owned by the current user/group, allowing any process started by this user to connect to it. 1Password CLI is owned by the `onepassword-cli` group and has the `set-gid` bit set on Linux. The 1Password app verifies the authenticity of 1Password CLI by checking if the GID of the process connecting on the unix socket is equal to that of the `onepassword-cli` group. If the GID doesn't match, the connection is reset before any messages are accepted. **Windows:** 1Password CLI connects to a named pipe opened by the 1Password app. The app verifies the authenticity of the process connecting on the named pipe by verifying the Authenticode signature of the process's executable. 1Password CLI verifies the 1Password app's authenticity in the same way. ### Authorization prompts The user is prompted for authorization to confirm that they actually want to allow an account to be accessible through 1Password CLI. **Mac:** On macOS the OS's default biometrics prompt is used to request authorization, if available. Either TouchID or an Apple Watch can be used to confirm this prompt. If biometrics are not available a prompt confirming the user's device password is used instead. **Linux:** On Linux, PolKit is used to spawn a prompt that includes an authentication challenge for the user (commonly fingerprint or the user's OS password). **Windows:** On Windows, Windows Hello is used to spawn a prompt that includes an authentication challenge for the user (commonly fingerprint, face, or the user's OS password). Without Windows Hello, biometrics cannot be used with 1Password CLI. --- ## Use the 1Password desktop app to sign in to 1Password CLI You can use the [1Password desktop app](https://1password.com/downloads) integration to quickly and securely sign in to [1Password CLI](/docs/cli/get-started/). The app integration allows you to: - Seamlessly sign to the 1Password accounts you've added to the app in your terminal. - Authenticate 1Password CLI the same way you unlock your device, like with your fingerprint, face, Apple Watch, Windows Hello PIN, or device user password. - Track recent 1Password CLI activity from your 1Password app. ## Requirements **Mac:** - [1Password subscription](https://1password.com/pricing/password-manager) - [1Password for Mac](https://1password.com/downloads/mac) **Windows:** - [1Password subscription](https://1password.com/pricing/password-manager) - [1Password for Windows](https://1password.com/downloads/windows) **Linux:** - [1Password subscription](https://1password.com/pricing/password-manager) - [1Password for Linux](https://1password.com/downloads/linux) - [PolKit](https://gitlab.freedesktop.org/polkit/polkit) (included in many popular distributions) - A PolKit authentication agent running ## Set up the app integration ### Step 1: Turn on the app integration **Mac:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 4. Select **Integrate with 1Password CLI**. 5. If you want to authenticate 1Password CLI with your fingerprint, turn on **[Touch ID](https://support.1password.com/touch-id-mac/)** in the app. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ **Windows:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Turn on **[Windows Hello](https://support.1password.com/windows-hello/)** in the app. 4. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 5. Select **Integrate with 1Password CLI**. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ **Linux:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Security](onepassword://settings/security)**. 4. Turn on **[Unlock using system authentication](https://support.1password.com/system-authentication-linux/)**. 5. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 6. Select **Integrate with 1Password CLI**. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ ### Step 2: Enter any command to sign in After you've turned on the app integration, enter any command and you'll be prompted to authenticate. For example, run this command to see all the vaults in your account: ```shell op vault list ``` #### If you have multiple accounts If you've added multiple 1Password accounts to your desktop app, you can use [`op signin`](/docs/cli/reference/commands/signin/) to select an account to sign in to with 1Password CLI. Use the arrow keys to choose from the list of all accounts added to your 1Password app. ```shell {2} op signin #code-result Select account [Use arrows to move, type to filter] > ACME Corp (acme.1password.com) AgileBits (agilebits.1password.com) Add another account ``` You can also [select an account on a per-command basis using the `--account` flag](/docs/cli/use-multiple-accounts#specify-an-account-per-command-with-the---account-flag) with your account's sign-in address or ID. ```shell op vault ls --account my.1password.com ``` If you're signed in to multiple accounts in the app but only want to use a specific account with 1Password CLI, you can [set the `OP_ACCOUNT` environment variable](/docs/cli/use-multiple-accounts#set-an-account-with-the-op_account-environment-variable) to your account's sign-in address or ID. ### Optional: Remove previously added account details :::warning[caution] Make sure you have access to your Secret Key and account password before removing account details from your configuration file. ::: If you previously [added an account to 1Password CLI manually](/docs/cli/sign-in-manually/) and now want to exclusively use the 1Password app to sign in, you can remove your account details from your configuration file. Your configuration file is in one of the following locations: - `~/.op/config` - `~/.config/op/config` - `~/.config/.op/config` Use the [account forget](/docs/cli/reference/management-commands/account#account-forget) command to remove all existing account information from your configuration file. This won't impact the accounts added to your 1Password app. ```shell op account forget --all ``` ### Optional: Set the biometric unlock environment variable You can use the `OP_BIOMETRIC_UNLOCK_ENABLED` environment variable to temporarily toggle the app integration on or off. **Bash, Zsh, sh:** To turn on the integration: ```shell export OP_BIOMETRIC_UNLOCK_ENABLED=true ``` To turn off the integration: ```shell export OP_BIOMETRIC_UNLOCK_ENABLED=false ``` **fish:** To turn on the integration: ```shell set -x OP_BIOMETRIC_UNLOCK_ENABLED true ``` To turn off the integration: ```shell set -x OP_BIOMETRIC_UNLOCK_ENABLED false ``` **PowerShell:** To turn on the integration: ```powershell $Env:OP_BIOMETRIC_UNLOCK_ENABLED = "true" ``` To turn off the integration: ```powershell $Env:OP_BIOMETRIC_UNLOCK_ENABLED = "false" ``` **Set a default account to use with the 1Password app integration**(Beta) Run `op account use` to set a default 1Password account to use with the 1Password app integration in your current terminal session. 1Password CLI will prompt you to select an account. ```shell op account use --account my.1password.com ``` ## Track 1Password CLI activity You can track 1Password CLI activity authenticated with the 1Password app, including the command, when it was run, the application where it was run, and the name of the account accessed. To see your 1Password CLI activity log: 1. Open and unlock the 1Password desktop app. 2. Select your account or collection at the top of the sidebar and choose **Settings** > [**Developer**](onepassword://settings/developers). 3. Turn on **Show 1Password Developer in Sidebar**. 4. Close the settings window, then select **Developer** in the sidebar. 5. Select **View CLI**. _[The 1Password CLI activity log.]_ You'll see a table with your recent 1Password CLI activity. Learn more about [1Password Developer](https://support.1password.com/developer/). ## Troubleshooting ### If `op signin` doesn't list your account `op signin` returns a list of all accounts you've added to the 1Password desktop app. To sign in to 1Password CLI with a new 1Password account, you'll need to [add the account to the app](https://support.1password.com/add-account/). ### If you see a connection error If you see a `connectionreset` error, or an error that 1Password CLI couldn't connect to the 1Password desktop app, try the following: **Mac:** Open **System Settings** > **General** > **Login Items** and make sure **Allow in background** is turned on for 1Password. If you still see an error, try the following: 1. Make sure you're using the latest version of the 1Password desktop app. 2. Restart the app. If you're using 1Password for Mac version 8.10.12 or earlier, the 1Password CLI binary must be located in the `/usr/local/bin/` directory. **Windows:** 1. Make sure you're using the latest version of the 1Password desktop app. 2. Restart the app. **Linux:** 1. Make sure you're using the latest version of the 1Password desktop app. 2. Restart the app. If you see a `LostConnectionToApp` error when you try to authenticate: **Mac:** Make sure the option to keep 1Password in the menu bar is turned on: 1. Open and unlock the 1Password desktop app. 2. Select your account or collection at the top of the sidebar. 3. Select **Settings** > **General**. 4. Make sure "Keep 1Password in the menu bar" is selected. **Windows:** Make sure the option to keep 1Password in the notification area is turned on: 1. Open and unlock the 1Password desktop app. 2. Select your account or collection at the top of the sidebar. 3. Select **Settings** > **General**. 4. Make sure "Keep 1Password in the notification area" is selected. **Linux:** Make sure the option to keep 1Password in the system tray is turned on: 1. Open and unlock the 1Password desktop app. 2. Select your account or collection at the top of the sidebar. 3. Select **Settings** > **General**. 4. Make sure "Keep 1Password in the system tray" is selected. ### If you aren't prompted to authenticate with your preferred method If you've turned on the app integration, but aren't prompted to sign in to 1Password CLI with your expected authentication method: **Mac:** Make sure you've set up [Touch ID](https://support.1password.com/touch-id-mac/) or an [Apple Watch](https://support.1password.com/apple-watch-mac/) to unlock 1Password on your Mac. **Windows:** Make sure you've set up [Windows Hello](https://support.1password.com/windows-hello/) to unlock 1Password on your Windows PC. **Linux:** 1. Make sure you've set up [system authentication](https://support.1password.com/system-authentication-linux/) to unlock 1Password on your Linux computer. 2. Update the authentication method in your Linux settings to use a [fingerprint](https://help.ubuntu.com/stable/ubuntu-help/session-fingerprint.html.en) or other biometrics instead of your Linux user password. ## Learn more - [Use multiple 1Password accounts with 1Password CLI](/docs/cli/use-multiple-accounts/) - [Add accounts to the 1Password app](https://support.1password.com/add-account/) - [1Password app integration security](/docs/cli/app-integration-security/) --- ## 1Password CLI best practices 1Password CLI brings 1Password to your terminal. The following are best practices we recommend when using 1Password CLI. ### Use the latest version of 1Password CLI Practice good software update hygiene and regularly update to the [latest version of the 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2). You can check for available updates with [`op update`](/docs/cli/reference/commands/update). ### Apply the principle of least privilege to your infrastructure secrets You can follow the [principle of least privilege ](https://csrc.nist.gov/glossary/term/least_privilege) with [1Password Service Accounts](/docs/service-accounts), which support restricting 1Password CLI access to only the items required for a given purpose. Use dedicated vaults with service accounts that are properly scoped for secrets management use cases. Do not grant access to more vaults than needed. Learn more about [managing group and vault permissions using the principle of least privilege](https://support.1password.com/business-security-practices#access-management-and-the-principle-of-least-privilege). ### Use template files when creating items that contain sensitive values When creating items with [`op item create`](/docs/cli/reference/management-commands/item#item-create) we recommend using a [JSON template](/docs/cli/item-create#with-an-item-json-template) to enter any sensitive values. --- ## How 1Password CLI detects configuration directories 1Password CLI configuration directories default to: - `${XDG_CONFIG_HOME}/op` when `${XDG_CONFIG_HOME}` is set - `~/.config/op` when `${XDG_CONFIG_HOME}` is not set 1Password CLI detects the configuration directory to read or write to in this order of precedence: 1. A directory specified with `--config` 2. A directory set with the `OP_CONFIG_DIR` environment variable. 3. `~/.op` (following [go-homedir ](https://github.com/mitchellh/go-homedir) to determine the home directory) 4. `${XDG_CONFIG_HOME}/.op` 5. `~/.config/op` (following [go-homedir ](https://github.com/mitchellh/go-homedir) to determine the home directory) 6. `${XDG_CONFIG_HOME}/op` --- ## 1Password CLI environment variables You can use the following environment variables with 1Password CLI: | Environment variable | Description | | --- | --- | | `OP_ACCOUNT` | Specifies a default 1Password account to execute commands. Accepts an [account sign-in address or ID](/docs/cli/use-multiple-accounts#find-an-account-sign-in-address-or-id). An account specified with the `--account` flag takes precedence.| | `OP_BIOMETRIC_UNLOCK_ENABLED` | Toggles the [1Password app integration](/docs/cli/app-integration#optional-set-the-biometric-unlock-environment-variable) on or off. Options: `true`, `false`. | | `OP_CACHE` | Toggles the option to [store and use cached information](/docs/cli/reference#cache-item-and-vault-information) on or off. Options: `true`, `false`. Default: `true`. | | `OP_CONFIG_DIR` | Specifies a [configuration directory](/docs/cli/config-directories) to read and write to. A directory specified with the `--config` flag takes precedence. | | `OP_CONNECT_HOST` | Sets a [Connect server instance host URL](/docs/connect/cli/) to use with 1Password CLI. | | `OP_CONNECT_TOKEN` | Sets a [Connect server token](/docs/connect/cli/) to use with 1Password CLI. | | `OP_DEBUG` | Toggles debug mode on or off. Options: `true`, `false`. Default: `false`.| | `OP_FORMAT` | Sets the output format for 1Password CLI commands. Options: `human-readable`, `json`. Default: `human-readable`.| | `OP_INCLUDE_ARCHIVE` | Allows items in the archive to be retrieved with [`op item get`](/docs/cli/reference/management-commands/item#item-get) and [`op document get`](/docs/cli/reference/management-commands/document#document-get) commands. Options: `true`, `false`. Default: `false`. | | `OP_ISO_TIMESTAMPS` | Toggles the option to format timestamps according to ISO 8601 and RFC 3339 standards on or off. Options: `true`, `false`. Default: `false`. | | `OP_RUN_NO_MASKING` | Toggles masking off for the output of [`op run`](/docs/cli/reference/commands/run). | | `OP_SESSION` | Stores a session token when you [sign in to 1Password CLI manually](/docs/cli/sign-in-manually). | | `OP_SERVICE_ACCOUNT_TOKEN` | Configures 1Password CLI to [authenticate with a service account](/docs/service-accounts/use-with-1password-cli). | --- ## Grant and revoke vault permissions With 1Password CLI, you can manage the permissions each [user](/docs/cli/reference/management-commands/vault#vault-user) or [group](/docs/cli/reference/management-commands/vault#vault-group) has in each vault, so that everyone has access to the items they need. Some permissions require [dependent permissions](/docs/cli/vault-permissions/). On interactive shells, you can specify any permission, and 1Password CLI will ask you whether you want to add or revoke dependent permissions. If you're using scripts, or your shell isn't interactive, you must [include dependent permissions](#scripting) in the command. [Learn what permissions are available for your account type.](/docs/cli/vault-permissions/) ## Requirements Before you can use 1Password CLI to , you'll need to: - Sign up for 1Password - Install 1Password CLI You can manage vault permissions if you're an owner, administrator, or if you have the `manage_vault` permission in a vault. ## Grant permissions in vaults ### Users Use [`op vault user grant`](/docs/cli/reference/management-commands/vault#vault-user-grant) to grant a user permissions in a vault. For example, to grant the user Wendy Appleseed permission to edit items and manage vault permissions in the Prod vault: ```shell op vault user grant --user wendy.appleseed@agilebits.com --vault Prod --permissions allow_editing,allow_managing ``` If the permissions you want to grant require dependent permissions to be granted alongside them, 1Password CLI will prompt you to grant those permissions: ``` In order to grant [allow_editing,allow_managing], the permission(s) [allow_viewing] are also required. Would you like to grant them as well? [Y/n] ``` To confirm which users have access to a vault and their current permissions: ```shell op vault user list ``` ### Groups Use [`op vault group grant`](/docs/cli/reference/management-commands/vault#vault-group-grant) to grant a group permissions in a vault. For example, to grant the group IT permission to edit items and manage vault permissions in the Prod vault: ```shell op vault group grant --group "IT" --vault Prod --permissions allow_editing,allow_managing ``` If the permissions you want to grant require dependent permissions to be granted alongside them, 1Password CLI will prompt you to grant those permissions: ``` In order to grant [allow_editing,allow_managing], the permission(s) [allow_viewing] are also required. Would you like to grant them as well? [Y/n] ``` To confirm which groups have access to a vault and their current permissions: ```shell op vault group list ``` ## Revoke permissions in vaults ### Users Use [`op vault user revoke`](/docs/cli/reference/management-commands/vault#vault-user-revoke) to revoke a user's permissions in a vault. For example, to revoke the user Wendy Appleseed's permission to view items in the Prod vault: ```shell op vault user revoke --user wendy.appleseed@agilebits.com --vault Prod --permissions allow_viewing ``` If the permission you want to revoke requires dependent permissions to be revoked alongside it, 1Password CLI will prompt you to revoke those permissions: ``` In order to revoke [allow_viewing], the permission(s) [allow_editing,allow_managing] are also required. Would you like to revoke them as well? [Y/n] ``` To confirm that the user's permissions have been revoked: ```shell op vault user list ``` ### Groups Use [`op vault group revoke`](/docs/cli/reference/management-commands/vault#vault-group-grant) to revoke a group's permissions in a vault. For example, to revoke the group IT's permission to view items in the Prod vault: ```shell op vault group revoke --group "IT" --vault Prod --permissions allow_viewing ``` If the permission you want to revoke requires dependent permissions to be revoked alongside it, 1Password CLI will prompt you to revoke those permissions: ``` In order to revoke [allow_viewing], the permission(s) [allow_editing,allow_managing] are also required. Would you like to revoke them as well? [Y/n] ``` To confirm the group's permissions have been revoked: ```shell op vault group list ``` ## Scripting If you're using scripts to grant and revoke vault permissions, or if your shell isn't interactive, you'll need to include the `--no-input` flag and specify all [dependent permissions](/docs/cli/vault-permissions/) in a comma-separated list after the `--permissions` flag. For example, the `allow_managing` permission requires the `allow_editing` and `allow_viewing` permission. To grant the user Wendy Appleseed permission to manage vault permissions in the Prod vault: ```shell op vault user grant --no-input --user wendy.appleseed@agilebits.com --vault Prod --permissions allow_managing,allow_editing,allow_viewing ``` To revoke `allow_editing` from a group that currently also has `allow_managing` granted in a vault: ```shell op vault group revoke --no-input --group "IT" --vault Prod --permissions allow_managing,allow_editing ``` ## Learn more - [Vault permission dependencies](/docs/cli/vault-permissions/) --- ## Install 1Password CLI on a server There are several different ways to install 1Password CLI on a server. To install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) on a Linux `amd64` host, you can use this one-line command: ```shell ARCH="amd64"; \ OP_VERSION="v$(curl https://app-updates.agilebits.com/check/1/0/CLI2/en/2.0.0/N -s | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+')"; \ curl -sSfo op.zip \ https://cache.agilebits.com/dist/1P/op2/pkg/"$OP_VERSION"/op_linux_"$ARCH"_"$OP_VERSION".zip \ && unzip -od /usr/local/bin/ op.zip \ && rm op.zip ``` To install with Docker, you can use the [1Password CLI 2 Docker image](https://hub.docker.com/r/1password/op/tags): ```shell docker pull 1password/op:2 ``` If you want to add the CLI installation to your Dockerfile, then add this line: ```docker title="Dockerfile" COPY --from=1password/op:2 /usr/local/bin/op /usr/local/bin/op ``` ## Learn more - [Install 1Password CLI on your machine](/docs/cli/get-started#step-1-install-1password-cli) --- ## Create items with 1Password CLI # Create items To create a new item in your 1Password account and assign information to it, use the [`op item create`](/docs/cli/reference/management-commands/item#item-create) command. You can [specify basic information about the item](#create-an-item) with flags and use assignment statements to [assign built-in and custom fields](#create-a-customized-item). To assign sensitive values, [use a JSON template](#with-an-item-json-template). ## Requirements Before you can use 1Password CLI to create items, you'll need to: - [Sign up for 1Password](https://1password.com/pricing/password-manager) - [Install 1Password CLI](/docs/cli/get-started#step-1-install-1password-cli) :::info Follow along If you want to follow along with the examples in this guide, [sign in to your account](/docs/cli/get-started#step-3-enter-any-command-to-sign-in) then create a new vault named `Tutorial` where the example items will be saved: ```shell op vault create Tutorial ``` ::: ## Create an item To create a new item, use [`op item create`](/docs/cli/reference/management-commands/item#item-create) and specify basic information about the item with flags. For example, to create a Login item named `Netflix` in the `Tutorial` vault: **Bash, Zsh, sh, fish:** ```shell [{ "badge": 1, "color": "tangerine", "lineNo": 2, "substr": "--category login" }, { "badge": 2, "color": "sunbeam", "lineNo": 3, "substr": "--title \\"Netflix\\"" }, { "badge": 3, "color": "lagoon", "lineNo": 4, "substr": "--vault Tutorial" }, { "badge": 4, "color": "intrepidblue", "lineNo": 5, "substr": "--url 'https://www.netflix.com/login'" }, { "badge": 5, "color": "bitsblue", "lineNo": 6, "substr": "--generate-password='letters,digits,symbols,32'" }, { "badge": 6, "color": "dahlia", "lineNo": 7, "substr": "--tags tutorial,entertainment" }] op item create \ --category login \ --title "Netflix" \ --vault Tutorial \ --url 'https://www.netflix.com/login' \ --generate-password='letters,digits,symbols,32' \ --tags tutorial,entertainment ``` **PowerShell:** ```powershell [{ "badge": 1, "color": "tangerine", "lineNo": 2, "substr": "--category login" }, { "badge": 2, "color": "sunbeam", "lineNo": 3, "substr": "--title \\"Netflix\\"" }, { "badge": 3, "color": "lagoon", "lineNo": 4, "substr": "--vault Tutorial" }, { "badge": 4, "color": "intrepidblue", "lineNo": 5, "substr": "--url 'https://www.netflix.com/login'" }, { "badge": 5, "color": "bitsblue", "lineNo": 6, "substr": "--generate-password='letters,digits,symbols,32'" }, { "badge": 6, "color": "dahlia", "lineNo": 7, "substr": "--tags tutorial,entertainment" }] op item create ` --category login ` --title "Netflix" ` --vault Tutorial ` --url 'https://www.netflix.com/login' ` --generate-password='letters,digits,symbols,32' ` --tags tutorial,entertainment ``` Here's what each of the above flags does: --category Sets the item category, in this case a Login item. Use `op item template list` to get a list of available categories. The category value is case-insensitive and ignores whitespace characters. For example, the `Social Security Number` category can also be specified as `socialsecuritynumber`. --title Gives the item a name so that you can easily identify it. If unspecified, 1Password CLI selects a default name. For example, `Untitled Login item`. --vault Specifies which vault the item should be created in. If unspecified, the item will be created in your built-in Personal, Private, or Employee vault. The name of this vault varies depending on your account type. --url Sets the website where 1Password suggests and fills a Login, Password, or API Credential item. --generate-password Generates a strong password for Login and Password category items. You can specify a password recipe, as shown in the example. If left unspecified, a default recipe will be used to generate a 32-character password consisting of letters, digits, and symbols. --tags Adds tags to the item using a comma-separated list. ## Create a customized item Each item category has its own set of built-in fields that you can use to save more information to the item. You can also create custom fields to save additional details about the item. Learn more about [built-in and custom fields](/docs/cli/item-fields/). You can assign built-in and custom fields to your item in two ways: - [With assignment statements](#with-assignment-statements) - [With an item JSON template](#with-an-item-json-template) ### With assignment statements :::danger Command arguments can be visible to other processes on your machine. If you're assigning sensitive values, use [an item JSON template](#with-an-item-json-template) instead. ::: The [`op item create`](/docs/cli/reference/management-commands/item#item-create) command can take a list of assignment statements as arguments to create fields on an item. Assignment statements are formatted like this: ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "
" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "" }] [
.][[]]= ``` - section (Optional) The name of the section where you want to create the field. - field The name of the field you want to create. - fieldType The type of field you want to create. If unspecified, `fieldType` will default to `password`. - value The information you want to save in the field. For built-in fields, the field name should match the [built-in field `id`](/docs/cli/item-fields#built-in-fields) in the item category template. Don't include a fieldType for built-in fields. For custom fields, the fieldType should match the [custom field `type`](/docs/cli/item-fields#custom-fields) you want to create. The field name can be anything you want. If you need to use periods, equal signs, or backslashes in the name of a section or field, use a backslash character to escape them. Don't use backslashes to escape the value. Here's an example of an assignment statement for the built-in field username on a Login item, set to john.doe@acme.org: ```shell [{ "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "username" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "john.doe@acme.org" }] 'username=john.doe@acme.org' ``` And here's an example of an assignment statement for a custom field type titled date, which is set to 2022-12-31, in a field named Renewal Date within a section titled Subscription Info: ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "Subscription Info" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "Renewal Date" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "date" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "2022-12-31" }] 'Subscription Info.Renewal Date[date]=2022-12-31' ``` To add both of the above assignment statements to a new item, `HBO Max`, in the `Tutorial` vault: **Bash, Zsh, sh, fish:** ```shell op item create \ --category login \ --title "HBO Max" \ --vault Tutorial \ --url 'https://www.hbomax.com' \ --generate-password='letters,digits,symbols,32' \ --tags tutorial,entertainment \ 'username=john.doe@acme.org' \ 'Subscription Info.Renewal Date[date]=2022-12-31' ``` **PowerShell:** ```powershell op item create ` --category login ` --title "HBO Max" ` --vault Tutorial ` --url 'https://www.hbomax.com' ` --generate-password='letters,digits,symbols,32' ` --tags tutorial,entertainment ` 'username=john.doe@acme.org' ` 'Subscription Info.Renewal Date[date]=2022-12-31' ``` ### With an item JSON template To assign sensitive values, fill out an item JSON template for the category of item you want to create. If you combine field assignment statements with a template, the assignment statements overwrite the template's values. To see a list of available templates, run [`op item template list`](/docs/cli/reference/management-commands/item#item-template-list). To get a template for a category, run [`op item template get `](/docs/cli/reference/management-commands/item#item-template-get). For example, to create a new Login item using a template: 1. Get the template for a Login item and save it in your current directory: ```shell op item template get --out-file=login.json "Login" ``` 2. Edit [the template file](/docs/cli/item-template-json/) to add your information. 3. Create the item using the `--template` flag to specify the path to the template file: ```shell op item create --template=login.json ``` This example template file creates a Login item named `Hulu` in a vault [specified by its ID](/docs/cli/reference#unique-identifiers-ids). It specifies values for built-in `username`, `password`, and `notesPlain` fields. It also adds a custom `date` field. **Example Login template** ```json title="login.json" { "title": "Hulu", "vault": { "id": "sor33rgjjcg2xykftymcmqm5am" }, "category": "LOGIN", "fields": [ { "id": "username", "type": "STRING", "purpose": "USERNAME", "label": "username", "value": "wendy.appleseed@gmail.com" }, { "id": "password", "type": "CONCEALED", "purpose": "PASSWORD", "label": "password", "password_details": { "strength": "" }, "value": "Dp2WxXfwN7VFJojENfEHLEBJmAGAxup@" }, { "id": "notesPlain", "type": "STRING", "purpose": "NOTES", "label": "notesPlain", "value": "This is Wendy's Hulu account." }, { "id": "date", "type": "date", "label": "Subscription renewal date", "value": "2023-04-05" } ] } ``` 4. Delete the edited template file from your computer. You can also create an item from standard input using a template: ```shell op item template get Login | op item create --vault Tutorial - ``` ## Create an item from an existing item You can create a new item from an existing item by piping the item JSON from standard input. For example, to create a new item based on the `HBO Max` item you created in the assignment statement section, with a new title, username, and password: ```shell op item get "HBO Max" --format json | op item create --vault Tutorial --title "Wendy's HBO Max" - 'username=wendy.appleseed@acme.org' 'password=Dp2WxXfwN7VFJojENfEHLEBJmAGAxup@' ``` ## Add a one-time password to an item You can attach a [one-time password](https://support.1password.com/one-time-passwords/) to an item using a custom field [assignment statement](#with-assignment-statements). The `fieldType` should be `otp` and the `value` should be the [otpauth:// URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format) for the one-time password. **Bash, Zsh, sh, fish:** ```shell op item create \ --category login \ --title='My OTP Example' \ --vault Tutorial \ --url 'https://www.acme.com/login' \ --generate-password='letters,digits,symbols,32' \ --tags tutorial,entertainment \ 'Test Section 1.Test Field3[otp]=otpauth://totp/:?secret=&issuer=' ``` **PowerShell:** ```powershell op item create ` --category login ` --title='My OTP Example' ` --vault Tutorial ` --url 'https://www.acme.com/login' ` --generate-password='letters,digits,symbols,32' ` --tags tutorial,entertainment ` 'Test Section 1.Test Field3[otp]=otpauth://totp/:?secret=&issuer=' ``` ## Attach a file to an item You can attach a file to an item using a custom field [assignment statement](#with-assignment-statements). The `field` should be the name the file will have in 1Password, the `fieldType` should be `file`, and the `value` should be the path to the file. ```shell myFileName[file]=/path/to/your/file ``` The file in the above example will be named `myFileName`. To preserve the original file name, you can omit the `field`: ```shell [file]=/path/to/your/file ``` Here's what an example `PlayStation Store` login would look like with the file `/wendyappleseed/documents/receipt.png` attached, named `JanuaryReceipt`. **Bash, Zsh, sh, fish:** ```shell op item create \ --category login \ --title "PlayStation Store" \ --vault Tutorial \ --url 'https://store.playstation.com/' \ --generate-password='letters,digits,symbols,32' \ --tags tutorial,entertainment \ 'JanuaryReceipt[file]=/wendyappleseed/documents/receipt.png' ``` **PowerShell:** ```powershell op item create ` --category login ` --title "PlayStation Store" ` --vault Tutorial ` --url 'https://store.playstation.com/' ` --generate-password='letters,digits,symbols,32' ` --tags tutorial,entertainment ` 'JanuaryReceipt[file]=/wendyappleseed/documents/receipt.png' ``` ## Next steps If you want to continue learning about item management, keep the example items you created and move on to the [edit items](/docs/cli/item-edit) tutorial. If you created a Tutorial vault and don't want to continue on, you can delete the vault and the examples items you created by running: ```shell op vault delete "Tutorial" ``` ## Learn more - [`op item create` reference documentation](/docs/cli/reference/management-commands/item#item-create) - [Built-in and custom item fields](/docs/cli/item-fields) - [Item JSON template](/docs/cli/item-template-json) --- ## Edit items with 1Password CLI # Edit items To edit an existing item in your 1Password account, use the [`op item edit`](/docs/cli/reference/management-commands/item#item-edit) command. You can [edit basic information about the item](#edit-an-items-basic-information) with flags and use assignment statements to [edit an item's built-in and custom fields](#edit-built-in-and-custom-fields). To edit sensitive values, [use a JSON template](#edit-an-item-using-a-json-template). You can't use `op item edit` to edit SSH keys. Learn more about managing SSH keys with 1Password CLI. ## Requirements Before you can use 1Password CLI to edit items, you'll need to: - [Sign up for 1Password](https://1password.com/pricing/password-manager) - [Install 1Password CLI](/docs/cli/get-started#step-1-install-1password-cli) :::info Follow along If you want to follow along with the examples in this guide, [create the example items in the guide to creating items](/docs/cli/item-create) first. ::: ## Edit an item's basic information To edit an item, use [`op item edit`](/docs/cli/reference/management-commands/item#item-edit) and specify the item by name, [unique identifier (ID)](/docs/cli/reference#unique-identifiers-ids), or sharing link. You can use flags to generate a new password and edit an item's title, vault, or tags. You can also change the website where 1Password suggests and fills a Login, Password, or API Credential item. For example, to change the name of the example item `Netflix`, move it from the `Tutorial` vault to the `Private` vault, update its tags, edit its website, and generate a new random password: **Bash, Zsh, sh, fish:** ```shell op item edit "Netflix" \ --title "Edited Netflix" \ --vault Private \ --tags tutorial \ --url https://www.netflix.com \ --generate-password='letters,digits,symbols,32' ``` **PowerShell:** ```powershell op item edit "Netflix" ` --title "Edited Netflix" ` --vault Private ` --tags tutorial ` --url https://www.netflix.com ` --generate-password='letters,digits,symbols,32' ``` To change the example item name back to `Netflix` and move it back to the `Tutorial` vault: **Bash, Zsh, sh, fish:** ```shell op item edit "Edited Netflix" \ --title "Netflix" \ --vault Tutorial ``` **PowerShell:** ```powershell op item edit "Edited Netflix" ` --title "Netflix" ` --vault Tutorial ``` ## Edit built-in and custom fields :::danger Command arguments can be visible to other processes on your machine. To edit sensitive values, use [an item JSON template](#edit-an-item-using-a-json-template) instead. ::: The `op item edit` command can take a list of assignment statements as arguments to edit an item's [built-in and custom fields](/docs/cli/item-fields). ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "
" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "" }] [
.][[]]= ``` - section (Optional) The name of the section where the field is saved. - field The name of the field. - fieldType The type of field. If unspecified, the fieldType stays the same. - value The information you want to save in the field. If unspecified, the value stays the same. For example, to change the subscription renewal date on the `HBO Max` item: **Bash, Zsh, sh, fish:** ```shell op item edit "HBO Max" \ 'Renewal Date=2023-5-15' ``` **PowerShell:** ```powershell op item edit "HBO Max" ` 'Renewal Date=2023-5-15' ``` ### Delete a custom field To delete a custom field, specify `[delete]` in place of the fieldType. If you remove all the fields in a section, the section is also removed. You can't delete empty fields, but you can set them to empty strings. To use an assignment statement to delete the subscription renewal date on the example `HBO Max` item: **Bash, Zsh, sh, fish:** ```shell op item edit "HBO Max" \ 'Renewal Date[delete]=2023-5-15' ``` **PowerShell:** ```powershell op item edit "HBO Max" ` 'Renewal Date[delete]=2023-5-15' ``` ## Edit an item using a JSON template :::danger JSON item templates do not support passkeys. If you use a JSON template to update an item that contains a passkey, the passkey will be overwritten. To fix this, you can [restore a previous version of the item](https://support.1password.com/item-history/). ::: To edit sensitive values on an item, use an [item JSON template](/docs/cli/item-template-json). 1. Get the JSON output for the item you want to edit and save it to a file. ```shell op item get --format json > newItem.json ``` If you prefer to start over, you can get a blank template for the item's category with `op item template get`. 2. Edit the file. 3. Use the `--template` flag to specify the path to the edited file and apply the changes to the item: ```shell op item edit --template=newItem.json ``` 4. Delete the file. You can also edit an item using piped input: ```shell cat newItem.json | op item edit ``` To avoid collisions, you can't combine piped input and the `--template` flag in the same command. ## Next steps If you created a Tutorial vault, you can delete the vault and the examples items you created: ```shell op vault delete "Tutorial" ``` ## Learn more - [`op item` reference documentation](/docs/cli/reference/management-commands/item) - [Built-in and custom item fields](/docs/cli/item-fields) - [Item JSON template](/docs/cli/item-template-json) --- ## Item fields When you [use 1Password CLI to create items](/docs/cli/item-create/), you can customize your items with [built-in](#built-in-fields) and [custom](#custom-fields) fields. Learn how to [add built-in and custom fields to your items](/docs/cli/item-create#create-a-customized-item) with either assignment statements or a JSON template. ## Built-in fields Each item category includes a set of default fields, some of which may be specific to the category. You can identify available built-in fields by looking at the [JSON template](/docs/cli/item-template-json/) for the item category: ``` op item template get ``` **View all categories** - API Credential - Bank Account - Credit Card - Crypto Wallet - Database - Document - Driver License - Email Account - Identity - Login - Medical Record - Membership - Outdoor License - Passport - Password - Reward Program - Secure Note - Server - Social Security Number - Software License - SSH Key - Wireless Router For example, the built-in fields available on a Login item are `username`, `password`, and `notesPlain`. **View a Login item JSON template** ```shell {6,13,23} { "title": "", "category": "LOGIN", "fields": [ { "id": "username", "type": "STRING", "purpose": "USERNAME", "label": "username", "value": "" }, { "id": "password", "type": "CONCEALED", "purpose": "PASSWORD", "label": "password", "password_details": { "strength": "TERRIBLE" }, "value": "" }, { "id": "notesPlain", "type": "STRING", "purpose": "NOTES", "label": "notesPlain", "value": "" } ] } ``` When you use [assignment statements](/docs/cli/item-create#with-assignment-statements) to assign built-in fields, use the `id` from the JSON template as the `field` in the assignment statement. Don't include a fieldType for built-in fields. For example, to add a note to a Login item using an assignment statement: ```shell 'notesPlain=This is a note.' ``` ## Custom fields Custom fields can be added to any item, regardless of the item's category. Use the `fieldType` with [assignment statements](/docs/cli/item-create#with-assignment-statements) and the `type` with an [item JSON template](/docs/cli/item-create#with-an-item-json-template). Available custom field types are: | `fieldType` | `type` | description | | --- | --- | --- | | `password` | `CONCEALED` | A concealed password. | | `text` | `STRING` | A text string. | | `email` | `EMAIL` | An email address. | | `url` | `URL` | A web address to copy or open in your default web browser, not used for autofill behavior. Use the `--url` flag to set the website where 1Password suggests and fills a Login, Password, or API Credential item. | | `date` | `DATE` | A date with the format `YYYY-MM-DD`. | | `monthYear` | `MONTH_YEAR` | A date with the format `YYYYMM` or `YYYY/MM`. | | `phone` | `PHONE` | A phone number. | | `otp` | `OTP` | A one-time password. Accepts an [`otpauth://` URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format) as the value. | | `file` | N/A | A file attachment. Accepts the path to the file as the value. Can only be added with [assignment statements](/docs/cli/item-create#with-assignment-statements). | ## Learn more - [`op item` reference documentation](/docs/cli/reference/management-commands/item/) - [Create an item](/docs/cli/item-create/) - [Item JSON template](/docs/cli/item-template-json/) --- ## Item JSON template 1Password CLI supports item JSON templates that you can use to take control of how you create items in 1Password. Item JSON templates allow you to [create an item with all of its details specified](/docs/cli/item-create#with-an-item-json-template), including custom sections and fields. Item templates are formatted similarly to the JSON output for [`op item get`](/docs/cli/reference/management-commands/item#item-get), so you can easily create new items based on existing items. Each item category has its own template. You can get a list of all item categories with [`op item template list`](/docs/cli/reference/management-commands/item#item-template-list). And you can retrieve the template for an item category with [`op item template get `](/docs/cli/reference/management-commands/item#item-template-get). ## Item template keys Item JSON templates have common language keys that allow you to identify how the fields in the template correspond to the item in 1Password. ```json [{ "badge": 1, "color": "tangerine", "lineNo": 2, "substr": "\\"title\\"" }, { "badge": 2, "color": "sunbeam", "lineNo": 3, "substr": "\\"category\\"" }, { "badge": 3, "color": "lagoon", "lineNo": 6, "substr": "\\"id\\"" }, { "badge": 4, "color": "bitsblue", "lineNo": 7, "substr": "\\"label\\"" }, { "badge": 5, "color": "lagoon", "lineNo": 12, "substr": "\\"id\\"" }, { "badge": 6, "color": "lagoon", "lineNo": 14, "substr": "\\"id\\"" }, { "badge": 7, "color": "intrepidblue", "lineNo": 16, "substr": "\\"type\\"" }, { "badge": 8, "color": "bitsblue", "lineNo": 17, "substr": "\\"label\\"" }, { "badge": 9, "color": "dahlia", "lineNo": 18, "substr": "\\"value\\"" }] { "title": " ", "category": " ", "sections": [ { "id": " ", "label": " " }, ], "fields": [ { "id": " ", "section": { "id": " " }, "type": " ", "label": " ", "value": " " } ] } ``` **Item** | Name | Description | | --- | --- | | title | The name of the item displayed in 1Password. | | category | The item's category. | **Section** | Name | Description | | --- | --- | | id | The identifier for the section. If the item has multiple sections, each ID must be unique. | | label | The name of the section displayed in 1Password. | To add a custom section, insert a section JSON object into the `sections` array. **View a section JSON object** ```json { "id": " ", "label": " " } ``` **Field** | Name | Description | | --- | --- | | id | The field's ID. Each ID should be unique. If left empty, 1Password will generate a random ID. | | section id | The ID of the section where the field is located. Only required if located in a custom section. | | type | The field's type. [Learn more about custom field types.](/docs/cli/item-fields#custom-fields) | | label | The name of the field displayed in 1Password. | | value | The information saved in the field. Depending on its type, it can be a string, a secret, a number, or a date. | To add a custom field to the template, insert a new field JSON object into the `fields` array. **View a field JSON object** ```json { "id": " ", "section": { "id": " " }, "type": " ", "label": " ", "value": " " } ``` ## Example JSON representation This is an item `mysql` in the 1Password app, and the same item represented in an item JSON template. **In the app:** _[MySQL item in 1Password]_ **In the JSON template:** ```json { "id": "4l3udxihvvuhszh2kxyjbblxl4", "title": "mysql", "version": 3, "vault": { "id": "uteieiwkhgv6hau7xkorejyvru" }, "category": "DATABASE", "last_edited_by": "IU2OKUBKAFGQPFPFZEG7X3NQ4U", "created_at": "2021-11-25T14:50:14Z", "updated_at": "2022-02-25T18:12:12Z", "sections": [ { "id": "g52gfotnw7nhnkgq477si2hmmi", "label": "Database Owner" } ], "fields": [ { "id": "notesPlain", "type": "STRING", "purpose": "NOTES", "label": "notesPlain" }, { "id": "database_type", "type": "MENU", "label": "type", "value": "mysql" }, { "id": "hostname", "type": "STRING", "label": "server", "value": "http://localhost" }, { "id": "port", "type": "STRING", "label": "port", "value": "5432" }, { "id": "database", "type": "STRING", "label": "database", "value": "app-database" }, { "id": "username", "type": "STRING", "label": "username", "value": "mysql-user" }, { "id": "password", "type": "CONCEALED", "label": "password", "value": "T4Kn7np2bLJXAFoYPoVC" }, { "id": "sid", "type": "STRING", "label": "SID" }, { "id": "alias", "type": "STRING", "label": "alias" }, { "id": "options", "type": "STRING", "label": "connection options" }, { "id": "tpcs7jrjikehw5o4tzbe5pklca", "section": { "id": "g52gfotnw7nhnkgq477si2hmmi", "label": "Database Owner" }, "type": "STRING", "label": "admin", "value": "Wendy Appleseed" }, { "id": "sdqueijyulxryvu5ceuwktjkiq", "section": { "id": "g52gfotnw7nhnkgq477si2hmmi", "label": "Database Owner" }, "type": "EMAIL", "label": "email", "value": "appleseed.wendy@gmail.com" } ] } ``` ## Learn more - [Create an item](/docs/cli/item-create/) - [Work with items](/docs/cli/reference/management-commands/item/) - [Work with vaults](/docs/cli/reference/management-commands/vault/) --- ## 1Password CLI 1Password CLI brings 1Password to your terminal. Sign in to 1Password CLI with your fingerprint, and securely access everything you need during development. ## Use cases - **Eliminate plaintext secrets in code**: Inject secrets from 1Password anywhere you need them. - **Automate administrative tasks**: Use scripts to manage items and provision team members at scale. - **Sign in to any CLI with your fingerprint**: Store API keys for your favorite CLIs in 1Password. ## [Quick start](/docs/cli/get-started/) If you're installing 1Password CLI for the first time, [start here](/docs/cli/get-started/). ## Guides ### Manage items and users - [Create and retrieve items](/docs/cli/item-create/). - [Add and remove team members](/docs/cli/provision-users/). - [Manage your team members' vault permissions](/docs/cli/grant-revoke-vault-permissions/). - [Manage your team members' group permissions](/docs/cli/reference/management-commands/group/). ### Provision secrets - [Securely load environment variables from 1Password Environments into your applications](/docs/cli/secrets-environment-variables/). - [Access secrets in your code with secret references](/docs/cli/secret-references/) instead of plaintext secrets. Secret references are replaced with the actual secrets they reference in 1Password at runtime. - [Securely load secrets from the environment into your applications](/docs/cli/secrets-environment-variables/) using secret references. - [Securely inject secrets into configuration files](/docs/cli/secrets-config-files/) using secret references. ### Authenticate with biometrics - [Use shell plugins to securely authenticate third-party CLIs](/docs/cli/shell-plugins/) with biometrics. - [Build your own shell plugin](/docs/cli/shell-plugins/contribute/) if the CLI you want to authenticate isn't already supported. ### Use 1Password CLI with other tools - Use [1Password for VS Code](/docs/vscode/) to bring 1Password CLI functionality to VS Code. - Use [1Password Service Accounts](/docs/service-accounts/get-started#create-a-service-account) to limit the vaults 1Password CLI can access or run automated scripts if your personal account uses SSO or MFA. - Use with [1Password Environments](/docs/environments) to quickly load your project secrets from 1Password. - Use a [1Password Connect Server](/docs/connect/cli/) with 1Password CLI to securely access your items in your company's apps and cloud infrastructure using a private REST API. - Use [1Password CI/CD Integrations](/docs/ci-cd/) with 1Password CLI to allow jobs in your pipeline to securely access secrets stored in 1Password. - Use the [1Password Events API](/docs/events-api/generic-scripts#usage) with 1Password CLI to provision bearer tokens at runtime using [secret references](/docs/cli/secret-references/). ## Reference documentation - Read the full [command reference](/docs/cli/reference/) to learn about all 1Password CLI commands and how they can be used. - Learn about [CLI best practices](/docs/cli/best-practices). - Learn about the [1Password app integration](/docs/cli/app-integration/). - Learn about the [shell plugins security model](/docs/cli/shell-plugins/security/). --- ## Add and remove team members with 1Password CLI # Add and remove team members ## Requirements Before you can use 1Password CLI to add and remove team members, you'll need to: 1. [Sign up for 1Password Business](https://1password.com/pricing/password-manager). 2. [Install 1Password CLI](/docs/cli/get-started#step-1-install-1password-cli). ## Turn on automated provisioning with 1Password CLI To get started, an owner or administrator must visit the [Provisioning settings page on 1Password.com](https://start.1password.com/settings/provisioning/cli) and select **Turn On CLI Provisioning**. This will create a [Provision Managers](https://support.1password.com/groups#provision-managers) group with the permissions needed to provision and confirm team members, as well as recover accounts. The person who created the group will be added to it. ## Manage who can provision team members By default, the owner or administrator who created the [Provision Managers](https://support.1password.com/groups#provision-managers) group is the only person added to it. If other team members need to be able to provision users, use [`op group user grant`](/docs/cli/reference/management-commands/group#group-user-grant) to add them to the group. For example, to add Wendy Appleseed to the Provision Managers group: ```shell op group user grant --group "Provision Managers" --user "wendy.appleseed@agilebits.com" ``` To see a list of everyone in the Provision Managers group: ```shell op group user list "Provision Managers" ``` ## Add team members To invite people to your team, use [`op user provision`](/docs/cli/reference/management-commands/user#user-provision) with the team member's name and email address. For example, to invite Wendy Appleseed to join your 1Password account: ```shell op user provision --name "Wendy Appleseed" --email "wendy.appleseed@agilebits.com" ``` The person will receive an email invitation to join the team. After they've accepted the invitation, a member of the Provision Managers group can confirm them. ## Confirm team members Anyone who belongs to the [Provision Managers](https://support.1password.com/groups#provision-managers) group can confirm new team members with [`op user confirm`](#with-op-user-confirm) or [on 1Password.com](#on-1passwordcom). ### With `op user confirm` To confirm a team member on the command line, use [`op user confirm`](/docs/cli/reference/management-commands/user#user-confirm) with their name or email address. To confirm all unconfirmed team members, include the `--all` flag. For example, to confirm Wendy Appleseed: ```shell op user confirm "wendy.appleseed@agilebits.com" ``` To confirm all pending users: ```shell op user confirm --all ``` ### On 1Password.com To confirm a team member on 1Password.com: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select **[People](https://start.1password.com/people)** in the sidebar. 3. Select the name of any team member with the Pending Provision status. 4. Select **Confirm** or **Reject**. If you don't see the option to confirm or reject a team member, ask your administrator to [add you to the Provision Managers group](#manage-who-can-provision-team-members). ## Remove team members To remove someone's access to vaults and items, you can suspend or delete their account. ### Suspend an account temporarily Use [`op user suspend`](/docs/cli/reference/management-commands/user#user-suspend) to suspend a team member temporarily. Include the `--deauthorize-devices-after` flag, followed by the number of seconds, minutes, or hours (for example, `600s`, `10m`, or `1h`) to set the time after suspension to deauthorize the suspended team member's devices. The maximum time permitted is 24 hours. If unspecified, their devices will be deauthorized immediately. For example, to suspend Wendy Appleseed temporarily and deauthorize her devices after 10 minutes: ```shell op user suspend "wendy.appleseed@agilebits.com --deauthorize-devices-after 10m" ``` You can reactivate a suspended user with [`op user reactivate`](/docs/cli/reference/management-commands/user#user-reactivate). ### Remove an account permanently Use [`op user delete`](/docs/cli/reference/management-commands/user#user-delete) to permanently remove a team member's access to vaults and items and delete all of their data from the account. For example, to remove Wendy Appleseed: ```shell op user delete "wendy.appleseed@agilebits.com" ``` ## Learn more - [Add and remove team members on 1Password.com](https://support.1password.com/add-remove-team-members/) - [Automate provisioning in 1Password Business using SCIM](https://support.1password.com/scim/) --- ## Recover accounts using 1Password CLI You can use 1Password CLI to begin the account recovery process for a family or team member if they can't sign in to or unlock 1Password. When you recover an account for someone: - They'll receive a new Secret Key and create a new 1Password account password. If your team uses Unlock with SSO, they'll be able to link a new app or browser to their account again. - They'll be able to access all the data they had before. - They'll need to sign in again on all their devices once recovery is complete. - Their two-factor authentication will be reset. ## Requirements - [Sign up for 1Password](https://1password.com/pricing/password-manager). - [Install 1Password CLI](/docs/cli/get-started#step-1-install-1password-cli) version `2.32.0` or later. You can recover accounts for other people if: - You're a team [administrator](https://support.1password.com/groups#administrators) or [owner](https://support.1password.com/groups#owners). - You belong to a [custom group](https://support.1password.com/custom-groups/) that has the "Recover Accounts" permission. - You're a [family organizer](https://support.1password.com/family-organizer/). ## Begin recovery Use the command `op user recovery begin` with a person's name, email address, or [unique identifier (ID)](/docs/cli/reference#unique-identifiers-ids) to begin the account recovery process. You can recover up to ten accounts with each command. ```shell op user recovery begin { | | } ``` For example, to begin recovery for multiple accounts using each person's ID: ```shell op user recovery begin ZMAE4RTRONHN7LGELNYYO373KM WHPOFIMMYFFITBVTOTZUR3R324 FGH76DFS89FYCU6342CSDWIFJU ``` The person whose account you're recovering will get an email from 1Password. When they select **Recover my account** in the email, a page will open in their browser and they'll be asked to confirm their email address. Then they'll get a new Secret Key and create a new account password. ## Complete recovery After the person whose account you recovered creates a new account password, you'll need to complete the recovery process before they can access their account. Learn how to [complete account recovery for one or more people](https://support.1password.com/recovery#complete-recovery). ## Learn more - [Add and remove team members](/docs/cli/provision-users) - [Grant and revoke vault permissions](/docs/cli/grant-revoke-vault-permissions) - [Sign back in to 1Password after your account has been recovered](https://support.1password.com/after-recovery/) --- ## Example scripts The 1Password Solutions team manages [a repository of example 1Password CLI scripts](https://github.com/1Password/solutions) that you can use as inspiration for your own projects. You'll need to install [jq](https://stedolan.github.io/jq/), a command-line JSON processor, for the example scripts to work correctly. You can find demo scripts to help you: - [Migrate from another password solution](https://github.com/1Password/solutions/tree/main/1password/migration) - [Provision new users from a CSV](https://github.com/1Password/solutions/tree/main/1password/scripted-provisioning) - [Audit or manage existing users](https://github.com/1Password/solutions/tree/main/1password/user-management) - [Manage your vaults and groups](https://github.com/1Password/solutions/tree/main/1password/account-management) - [Create, update, and share items](https://github.com/1Password/solutions/tree/main/1password/item-management) ## Learn more - [Get started with secret references](/docs/cli/secret-references/) - [Load secrets into scripts](/docs/cli/secrets-scripts/) - [Load secrets into the environment](/docs/cli/secrets-environment-variables/) - [Load secrets into config files](/docs/cli/secrets-config-files/) --- ## 1Password CLI Secret Reference Syntax # Secret reference syntax _[An environment file using a plaintext secret and the same file using a secret reference.]_ Secret reference URIs point to where a secret is saved in your 1Password account using the names (or [unique identifiers](/docs/cli/reference#unique-identifiers-ids)) of the vault, item, section, and field where the information is stored. ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "vault-name" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "item-name" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "section-name" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "field-name" }] op:////[section-name/] ``` 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 CLI**: Load secrets into environment variables, configuration files, and scripts. Learn more - **1Password SDKs**: Programmatically access your secrets with Go, JavaScript, and Python. Learn more - **Secrets Automation**: Use secret references to secure your secrets management workflows. Learn more - **VS Code**: Create, preview, and read secret references in your code. Learn more - **1Password integrations**: Securely access your secrets in Kubernetes, CircleCI, GitHub Actions, Jenkins, Terraform, Pulumi, Postman, and more. Learn more ## Get 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](/docs/cli/app-integration). Then: 1. Open the item where the secret you want to reference is stored. 2. Select next to the field that contains the secret you want to reference, then select Copy Secret Reference. _[An item in 1Password with the Copy Secret Reference option selected.]_ ### With 1Password for VS Code You can use 1Password for VS Code to [insert secret references](/docs/vscode#get-values) from 1Password as you edit your code. First, [install the extension](/docs/vscode/). Then: 1. Open the **[Command Palette ](https://code.visualstudio.com/api/ux-guidelines/command-palette)**. 2. Enter `1Password: Get from 1Password`. 3. Enter the item name or ID. 4. Select the field to use. ### With 1Password CLI To get a secret reference with 1Password CLI, run [`op item get`](/docs/cli/reference/management-commands/item#item-get) with the `--format json` flag and include the `--fields` flag to specify a field label. Then use [jq ](https://jqlang.github.io/jq/) to retrieve the secret reference from the JSON output. For example: ```shell op item get GitHub --format json --fields username | jq .reference #code-result "op://development/GitHub/username" ``` To get secret references for every field on an item, use [`op item get`](/docs/cli/reference/management-commands/item#item-get) with the `--format json` flag without specifying a field. **Example JSON output** ```shell op item get GitHub --format json ``` Each field object will include a `reference` key that contains its secret reference. For the example `GitHub` item, the output looks like this: ```json {8,17,29,40} "fields": [ { "id": "username", "type": "STRING", "purpose": "USERNAME", "label": "username", "value": "wendy_appleseed@agilebits.com", "reference": "op://development/GitHub/username" }, { "id": "password", "type": "CONCEALED", "purpose": "PASSWORD", "label": "password", "value": "GADbhK6MjNZrRftGMqto", "entropy": 115.5291519165039, "reference": "op://development/GitHub/password", "password_details": { "entropy": 115, "generated": true, "strength": "FANTASTIC" } }, { "id": "notesPlain", "type": "STRING", "purpose": "NOTES", "label": "notesPlain", "reference": "op://development/GitHub/notesPlain" }, { "id": "5ni6bw735myujqe4elwbzuf2ee", "section": { "id": "hv46kvrohfj75q6g45km2uultq", "label": "credentials" }, "type": "CONCEALED", "label": "personal_token", "value": "ghp_WzgPAEutsFRZH9uxWYtw", "reference": "op://development/GitHub/credentials/personal_token" } ] } ``` ## 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: ```shell op read "op://development/aws/Access Keys/access_key_id" ``` Any part of a secret reference that includes an unsupported character must be referred to by its [unique identifier (ID)](/docs/cli/reference#unique-identifiers-ids) instead of its name. To get an ID, run [`op item get`](/docs/cli/reference/management-commands/item#item-get) with the output set to JSON. For example, to get the ID for a custom text field named `test/`: ``` op item get PagerDuty --fields label=test/ --format json #code-result { "id": "hu4vwo3bjkawq2uw2fkn5pkjzu", "section": { "id": "add more" }, "type": "STRING", "label": "text/", "value": "t", "reference": "op://Management/PagerDuty/add more/hu4vwo3bjkawq2uw2fkn5pkjzu" } ``` ### File attachments To reference a file attachment, use the file name in place of a field name: ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "vault-name" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "item-name" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "section-name" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "file-name" }] op://vault-name/item-name/[section-name/]file-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`. ```shell title="app.env" MYSQL_DATABASE = "op://$APP_ENV/mysql/database" MYSQL_USERNAME = "op://$APP_ENV/mysql/username" MYSQL_PASSWORD = "op://$APP_ENV/mysql/password" ``` Learn how to use variables to switch between sets of secrets in [environment files](/docs/cli/secrets-environment-variables#step-3-differentiate-between-environments) and [config files](/docs/cli/secrets-config-files#step-3-differentiate-between-environments). ### 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. ```html title="Fields" op:///[/
]/?attribute= ``` ```html title="File attachments" op:///[/
]/?attribute= ``` 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: ```shell op read "op://development/GitHub/Security/one-time password?attribute=otp" #code-result 359836 ``` To retrieve a field's type: ```shell op read "op://Personal/aws/access credentials/username?attribute=type" #code-result string ``` To retrieve the name of a file attachment: ```shell op read "op://app-infra/ssh/key.pem?attribute=name" #code-result key.pem ``` #### 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. ```shell op read "op://Private/ssh keys/ssh key/private key?ssh-format=openssh" #code-result -----BEGIN OPENSSH PRIVATE KEY----- b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABD3rRrf8J ruD0CxZTYfpbTYAAAAEAAAAAEAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIJ5B/GnxX6t9jMwQ G7QE7r5daJLkMKTZhNZhWfvzK2y+AAAAkLgQAivYu/+12/YrZhK5keIAZf4ZgsZsZ2JI2q qbx23PqgO93oGy1iCxXe3kngQL4cM6lwOZPsZPKCinkN6KxEr6RnXqFRHJbMpOiGeZhTuD rjeo77HqFdxDqDeckB77XCKL0Ew28H5JlM/WO31XR3Z4VBAgTe+BQLjrFV8WU5UX38hpBJ PMJyRsK72ZUDDaGQ== -----END OPENSSH PRIVATE KEY----- ``` ## 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: ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "Management" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "PagerDuty" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "Admin" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "email" }] op://Management/PagerDuty/Admin/email ``` - 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 _[PagerDuty 1Password item]_ ### A field without a section To create a secret reference for the Stripe publishable-key field, which is not part of a section, use: ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "dev" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "Stripe" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "publishable-key" }] op://dev/Stripe/publishable-key ``` - 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 _[Stripe 1Password item]_ ## Learn more - [Use secret references with 1Password CLI](/docs/cli/secret-references/) - [Get started with 1Password SDKs](/docs/sdks/) - [Load secrets into config files](/docs/cli/secrets-config-files/) - [Load secrets into the environment](/docs/cli/secrets-environment-variables/) - [Template syntax](/docs/cli/secrets-template-syntax/) --- ## Use secret references with 1Password CLI :::tip New beta feature You can now [pass secrets as environment variables](/docs/cli/secrets-environment-variables) to applications or scripts from [1Password Environments](/docs/environments). This allows you to more easily access project secrets from 1Password without the need to create secret references. ::: With 1Password CLI, you can use [secret references](/docs/cli/secret-reference-syntax) to securely load information saved in 1Password into environment variables, configuration files, and scripts without exposing any secrets in plaintext. A secret reference URI includes the names (or [unique identifiers](/docs/cli/reference#unique-identifiers-ids)) of the vault, item, section, and field where a secret is stored in your 1Password account: ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "vault-name" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "item-name" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "section-name" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "field-name" }] op:////[section-name/] ``` To replace secret references with the secrets they refer to at runtime, use [`op read`](#with-op-read), [`op run`](#with-op-run), or [`op inject`](#with-op-inject). :::tip We recommend using [1Password Service Accounts](/docs/service-accounts/) to follow the [principle of least privilege](/docs/cli/best-practices/). 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 with 1Password CLI, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install 1Password CLI.](/docs/cli/get-started#step-1-install-1password-cli) 3. Save the secrets you want to reference in your 1Password account. ## Step 1: Get secret references You can get secret references in several ways: - [With the 1Password desktop app](/docs/cli/secret-reference-syntax#with-the-1password-desktop-app): Copy secret references from the app. - [With 1Password for VS Code](/docs/vscode#get-values): Insert secret references from 1Password as you edit code. - [With 1Password CLI](/docs/cli/secret-reference-syntax#with-1password-cli): Get secret references for one or multiple fields with `op item get`. - [With the secret reference syntax](/docs/cli/secret-reference-syntax#syntax-rules): Write secret references manually. ## Step 2: Replace plaintext secrets with secret references After you create secret references, use them in place of plaintext secrets in your code. The example below shows a GitHub environment file with a secret reference pointing to where the GitHub Personal Access Token is stored in 1Password rather than a plaintext token. _[An environment file using a plaintext secret and the same file using a secret reference.]_ ## Step 3: Resolve secret references There are three ways you can replace secret references with the actual secrets they reference at runtime: - [Use `op read` to write secrets to `stdout` or to a file.](#with-op-read) - [Use `op run` to pass secrets as environment variables to a process.](#with-op-run) - [Use `op inject` to inject secrets into configuration files or scripts.](#with-op-inject) ### With `op read` You can use [`op read`](/docs/cli/reference/commands/read/) with a secret reference to print the secret to `stdout`. ```shell op read op://development/GitHub/credentials/personal_token #code-result ghp_WzgPAEutsFRZH9uxWYtw ``` 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: ```shell op read --out-file token.txt op://development/GitHub/credentials/personal_token ``` ```shell title="token.txt" ghp_WzgPAEutsFRZH9uxWYtw ``` You can also use `op read` with secret references to [load secrets into scripts](/docs/cli/secrets-scripts/). For example, to use secret references in place of your Docker username and password with the `docker login` command: ```shell title="myscript.sh" #!/bin/bash docker login -u "$(op read op://prod/docker/username)" -p "$(op read op://prod/docker/password)" ``` #### Query parameters You can use secret references with [query parameters](/docs/cli/secret-reference-syntax#field-and-file-metadata-attributes) 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. ```shell op:///[/
]/?attribute= ``` 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: ```shell op read "op://development/GitHub/Security/one-time password?attribute=otp" #code-result 359836 ``` 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. ```shell op read "op://Private/ssh keys/ssh key/private key?ssh-format=openssh" #code-result -----BEGIN OPENSSH PRIVATE KEY----- b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABD3rRrf8J ruD0CxZTYfpbTYAAAAEAAAAAEAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIJ5B/GnxX6t9jMwQ G7QE7r5daJLkMKTZhNZhWfvzK2y+AAAAkLgQAivYu/+12/YrZhK5keIAZf4ZgsZsZ2JI2q qbx23PqgO93oGy1iCxXe3kngQL4cM6lwOZPsZPKCinkN6KxEr6RnXqFRHJbMpOiGeZhTuD rjeo77HqFdxDqDeckB77XCKL0Ew28H5JlM/WO31XR3Z4VBAgTe+BQLjrFV8WU5UX38hpBJ PMJyRsK72ZUDDaGQ== -----END OPENSSH PRIVATE KEY----- ``` :::info Next step Learn more about [securely loading secrets into scripts](/docs/cli/secrets-scripts/). ::: ### With `op run` You can set environment variables to secret references, then use [`op run`](/docs/cli/reference/commands/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. :::note When you reference a variable like `$MY_VAR` in the **same command** where you call `op run`, your shell expands `$MY_VAR` before `op run` can substitute the secret reference. To make sure `op run` substitutes the secret before the variable expands, you can either: - **Export the variable** as a secret reference before calling `op run`, or - Set the variable in the same command as `op run`, then **run the command to expand the variable in a subshell**. For example: ```shell MY_VAR=op://vault/item/field op run --no-masking -- sh -c 'echo "$MY_VAR"' ``` ::: #### 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: ```shell $ node app.js [INFO] Launching Node.js app... [ERROR] Missing credentials DB_USER and DB_PASSWORD [INFO] Exiting with code 1 ``` You can set the `DB_USER` and `DB_PASSWORD` environment variables to secret references: **Bash, Zsh, sh:** ```shell export DB_USER="op://app-dev/db/user" export DB_PASSWORD="op://app-dev/db/password" ``` **fish:** ```shell set -x DB_USER="op://app-dev/db/user" set -x DB_PASSWORD="op://app-dev/db/password" ``` **PowerShell:** ```powershell $Env:DB_USER = "DB_USER=op://app-dev/db/user" $Env:DB_PASSWORD = "DB_PASSWORD=op://app-dev/db/password" ``` Then use `op run` to pass the secrets to the `node app.js` command: ```shell op run -- node app.js [INFO] Launching Node.js app... [DEBUG] ✔ Connected to db as user 'mydbuser' with password '' ``` #### 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: ```html title="node.env" DB_USER="op://app-dev/db/user" DB_PASSWORD="op://app-dev/db/password" ``` Then use `op run` with the `--env-file` flag: ```shell op run --env-file="./node.env" -- node app.js ``` #### Print a secret with or without masking 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. **Bash, Zsh, sh:** To export an example environment variable `DB_PASSWORD` to a secret reference: ```shell export DB_PASSWORD=op://app-prod/db/password ``` Use `op run` with the `printenv` command to print the concealed secret: ```shell op run -- printenv DB_PASSWORD #code-result ``` Include the `--no-masking` flag to print the actual secret: ```shell op run --no-masking -- printenv DB_PASSWORD #code-result fX6nWkhANeyGE27SQGhYQ ``` **fish:** To export an example environment variable `DB_PASSWORD` to a secret reference: ```shell set -x DB_PASSWORD=op://app-prod/db/password ``` Use `op run` with the `printenv` command to print the concealed secret: ```shell op run -- printenv DB_PASSWORD #code-result ``` Include the `--no-masking` flag to print the actual secret: ```shell op run --no-masking -- printenv DB_PASSWORD #code-result fX6nWkhANeyGE27SQGhYQ ``` **PowerShell:** To export an example environment variable `DB_PASSWORD` to a secret reference: ```powershell $Env:DB_PASSWORD = "DB_PASSWORD=op://app-prod/db/password" ``` To print the concealed secret: ```powershell op run -- powershell -c '$env:DB_PASSWORD' #code-result ``` Include the `--no-masking` flag to print the actual secret: ```powershell op run --no-masking -- powershell -c '$env:DB_PASSWORD' #code-result fX6nWkhANeyGE27SQGhYQ ``` :::info Next step Learn more about [loading secrets into the environment](/docs/cli/secrets-environment-variables/) 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`](/docs/cli/reference/commands/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: ```shell echo "here is my GitHub token: op://development/GitHub/credentials/personal_token" | op inject #code-result here is my GitHub token: ghp_WzgPAEutsFRZH9uxWYtw ``` To write the output to a file `token.txt` in the current directory: ```shell echo "here is my GitHub token: op://development/GitHub/credentials/personal_token" >> token.txt | op inject --out-file token.txt ``` ```shell title="token.txt" here is my GitHub token: ghp_WzgPAEutsFRZH9uxWYtw ``` #### 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. ```yaml title="config.yml.tpl" database: host: http://localhost port: 5432 username: op://prod/mysql/username password: op://prod/mysql/password ``` ```shell op inject --in-file config.yml.tpl --out-file config.yml ``` :::info Next step Learn more about [loading secrets into configuration files](/docs/cli/secrets-config-files/) with `op inject`, including how to use template variables to switch between different sets of secrets for different environments. ::: ## Learn more - [Secret reference syntax](/docs/cli/secret-reference-syntax/) - [Load secrets into the environment](/docs/cli/secrets-environment-variables/) - [Load secrets into config files](/docs/cli/secrets-config-files/) - [Load secrets into scripts](/docs/cli/secrets-scripts/) - [Use service accounts with 1Password CLI](/docs/service-accounts/use-with-1password-cli) --- ## Inject Secrets Into Config Files # Load secrets into config files With 1Password CLI, you can use [secret references](/docs/cli/secret-reference-syntax/) to automatically load secrets into configuration files from your 1Password account without putting any plaintext secrets in code. This allows you to check config files into source control and keep them in sync throughout developer workstations, CI, and production servers, which is otherwise manual and error-prone work. :::tip We recommend using [1Password Service Accounts](/docs/service-accounts/) to follow the [principle of least privilege](/docs/cli/best-practices/). 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 1Password to secure your config files, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install 1Password CLI.](/docs/cli/get-started#step-1-install-1password-cli) 3. Store the secrets you want to provision in your 1Password account. ## Step 1: Get secret references You can get secret references in several ways: - [With the 1Password desktop app](/docs/cli/secret-reference-syntax#with-the-1password-desktop-app): Copy secret references from the app. - [With 1Password for VSCode](/docs/vscode#get-values): Insert secret references from 1Password as you edit code. - [With 1Password CLI](/docs/cli/secret-reference-syntax#with-1password-cli): Get secret references for one or multiple fields with `op item get`. - Use the [secret reference syntax rules](/docs/cli/secret-reference-syntax#syntax-rules) to write secret references manually. ## Step 2: Use secret references in your config file Replace the plaintext secrets in your config file with the appropriate secret references, following the [template syntax](/docs/cli/secrets-template-syntax/). For example, if you start with a config file that looks like this: ```yaml title="config.yml" database: host: http://localhost port: 5432 username: mysql-user password: piG1rX5P1QMF6J5k7u7sNb ``` And you saved the `username` and `password` secrets on the `mysql` item in the `prod` vault, you would end up with this templated config file: ```yaml title="config.yml.tpl" database: host: http://localhost port: 5432 username: op://prod/mysql/username password: op://prod/mysql/password ``` ## Step 2: Inject the secrets To load secrets from the config file and provision them at runtime, use `op inject` to inject the secrets directly into your production environment. For example: ```zsh op inject -i config.yml.tpl -o config.yml ``` In the output file, `config.yml`, you'll see the secret references replaced with the plaintext secrets they reference. The config file template is stored together with the code in source control, so that every developer can see the structure of the file. :::danger Make sure to delete the resolved config file when you no longer need it. ::: ## Step 3: Differentiate between environments We highly recommend you organize your 1Password items in the same way across all of your environments. For example: `app/dev/db/password` and `app/prod/db/password`. If you do this, you can use variables in your template file to switch to a different set of secrets. You can have variables for your environment, stage, region, or anything else. For example: ```yaml title="config.yml.tpl" database: host: http://localhost port: 5432 username: op://$APP_ENV/mysql/username password: op://$APP_ENV/mysql/password ``` You can then set the `APP_ENV` variable when you inject into the template, using the [Template Syntax](/docs/cli/secrets-template-syntax/): **Bash, Zsh, sh, fish:** ```shell APP_ENV=prod op inject -i config.yml.tpl -o config.yml ``` **PowerShell:** 1. Set `APP_ENV` to `prod`: ```powershell $Env:APP_ENV = "prod" ``` 2. Inject the secrets: ```powershell op inject -i config.yml.tpl -o config.yml ``` This allows you to use the same template file, stored in source control next to your application, for all your deployments. ## Optional: Use `op inject` in production Now that the application works with the right configuration locally, you can use 1Password CLI to provision secrets in production environments. To do this, you'll first need to: 1. [Install 1Password CLI 2 in your production environment.](/docs/cli/install-server/) 2. [Set up a Secrets Automation workflow](/docs/connect/). 3. [Deploy 1Password Connect Server](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) and make it accessible to your production environment. To use 1Password CLI with a Connect server, set the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables to your Connect instance's credentials in your production environment. You can now move your secrets to config files and have them readily accessible with `op inject`. The following commands can be used with a Connect server: - `op run` - `op inject` - `op read` - `op item get` ## Learn more - [Load secrets into the environment](/docs/cli/secrets-environment-variables/) - [Secret reference syntax](/docs/cli/secret-reference-syntax/) - [Template syntax](/docs/cli/secrets-template-syntax/) --- ## Load secrets into the environment With [`op run`](/docs/cli/reference/commands/run/), you can provide your project secrets directly from 1Password to an application or script as environment variables at runtime. You can use `op run` with [1Password Environments](/docs/environments), environment variables set to [secret references](/docs/cli/secret-references), or a combination of both. 1Password CLI loads the specified secrets, then runs the provided command in a subprocess with the secrets made available as environment variables only for the duration of the process. This allows you to avoid hardcoding any plaintext secrets and quickly switch between different sets of secrets for different development contexts. ## Choose your configuration 1Password CLI provides multiple methods to load your project secrets: - **[1Password Environments (beta)](/docs/environments)** allow you to create Environments in 1Password that contain all your environment variables for a specific workflow. You can share Environments with your team and create separate Environments for each project, application, or development context (like staging or production). - **[Secret references](/docs/cli/secret-references)** are URIs that point to where a secret is stored in your 1Password account. A secret reference uses the names or unique identifiers of the vault, item, section, and field where the secret is stored in 1Password. You can set environment variables to secret references on the command line or use secret references in your `.env` files. Secret references require more manual setup than 1Password Environments to switch between different sets of environment variables for different contexts, or create shared team workflows. - **Hybrid approach**: You can use `op run` to load variables from a 1Password Environment alongside secret references from `.env` files or exported environment variables. :::tip Authenticate with a [1Password Service Account](/docs/service-accounts/) to follow the [principle of least privilege](/docs/cli/best-practices/). You can scope service account access to specific vaults and 1Password Environments so that processes in your authorized terminal session can only access secrets required for a given purpose. ::: :::warning[caution] You should assume that processes on your computer can access the environment of other processes run by the same user. Be aware of this when supplying secrets through environment variables. ::: ## Requirements **1Password Environment (beta):** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install the latest beta build of 1Password CLI](/docs/cli/reference#beta-builds), version `2.33.0-beta.02` or later. **Secret references:** Before you can load secrets into the environment, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install 1Password CLI.](/docs/cli/get-started#step-1-install-1password-cli) ## Step 1: Store your project secrets in 1Password **1Password Environment (beta):** To store your project secrets in a 1Password Environment, [follow the steps to create an Environment](/docs/environments), then import a `.env` file or manually add your environment variables. **Secret references:** To use secret references, save your project secrets as items in a vault in your 1Password account. Then follow the instructions to create secret references for each item using your preferred method: - [With the 1Password desktop app](/docs/cli/secret-reference-syntax#with-the-1password-desktop-app): Copy secret references from the app. - [With 1Password for VSCode](/docs/vscode#get-values): Insert secret references from 1Password as you edit code. - [With 1Password CLI](/docs/cli/secret-reference-syntax#with-1password-cli): Get secret references for one or multiple fields with `op item get`. - Use the [secret reference syntax rules](/docs/cli/secret-reference-syntax#syntax-rules) to write secret references manually. ## Step 2: Pass the secrets to the application **1Password Environment (beta):** To pass your environment variables from 1Password to an application or script: 1. Open the 1Password app and navigate to **Developer** > **Environments**. 2. Select the Environment where your project secrets are stored, then select **Manage environment** > **Copy environment ID**. 3. Use `op run --` with the command for starting the application or script. 1Password will run the provided command in a subprocess with the secrets made available as environment variables for the duration of the process. ```shell op run --environment -- ``` For example: ```shell op run --environment blgexucrwfr2dtsxe2q4uu7dp4 -- ./my-script.sh ``` **Secret references:** Step 1: Map secret references to environment variables To pass secrets to an application or script using `op run` and [secret references](/docs/cli/secret-references), you must first map the secret references to the appropriate environment variables. To do this, you can set environment variables to secret references using an environment file or export them on the command line. **Environment file:** Environment (`.env`) files allow you to define multiple environment variables as secret references with `KEY=VALUE` statements separated by a newline. To use an environment file with `op run`, add key-value pairs for each of your project secrets with the value set to a [secret reference](/docs/cli/secret-references). For example: ```shell title="prod.env" AWS_ACCESS_KEY_ID="op://development/aws/Access Keys/access_key_id" AWS_SECRET_ACCESS_KEY="op://development/aws/Access Keys/secret_access_key" ``` **Environment file syntax rules** The `.env` file parsing engine follows the following rules: - Environment variables are defined as `KEY=VALUE` statements separated by a newline. - Variables can span multiple lines if they are enclosed in either `'` or `"`: ``` MY_VAR = "this is on the first line and this is on the second line" ``` - Empty lines are skipped. - Lines beginning with `#` are treated as comments. Comments can also be placed inline after `KEY=VALUE` statements. - Empty values become empty strings. For example, `EMPTY=` will set the environment variable `EMPTY` to the empty string. - If a value is surrounded by single or double quotes, these quotes do not end up in the evaluated value. So `KEY="VALUE"` and `KEY='VALUE'` both evaluate to `KEY` and `VALUE`. - Occurrences of `$VAR_NAME` or `${VAR_NAME}` are replaced with their respective value from the environment. - A variable defined in a .env file can be referred to later in the same file: ``` SOME_VAR = value OTHER_VAR = ${SOME_VAR} ``` - Special characters can be escaped with `\`. For example, `MY_VAR = "\$SOME_VAR that is not actually replaced."` results in the following value for MY_VAR: `$SOME_VAR that is not actually replaced.`. - Inner quotes are maintained, so `JSON={"foo":"bar"}` evaluates to `JSON` and `{"foo":"bar"}`. - Variables do not get replaced in values that are enclosed in single quotes. So `KEY='$SOME_VAR'` evaluates to `KEY` and `$SOME_VAR`. - Template syntax can be used in the `VALUE` to inject secrets. The `KEY` can only contain template variables. - Template parsing is performed after `.env` file parsing, so you cannot use the former to construct the latter. - Leading and trailing whitespace of both `KEY` and `VALUE` segments are ignored, so `KEY = VALUE` is parsed the same as `KEY=VALUE`. - Single and double quoted values maintain both leading and trailing whitespace, so `KEY=" some value "` evaluates to `KEY` and ` some value `. - These files should use UTF-8 character encoding. Optional: Differentiate between environments :::tip If you need to pass secrets for multiple environments, we recommend using 1Password Environments instead of secret references. 1Password Environments allow you to more easily organize, share, and pass environment variables for multiple contexts. ::: If you have different sets of secrets for different environments, like staging and production, you can check a single environment file into source control and include a variable within the secret references to represent the context. You can then set the variable to the appropriate context when you pass the file to `op run`. To use this approach, you must organize your project secrets in 1Password into different vaults for each environment, with each item's fields structured in the same way. For example: `dev/mysql/password` and `prod/mysql/password`. Then, include an externally set variable (`$VARIABLE_NAME`) in place of the vault name for each secret reference in your environment file. For example, in the following environment file, `$APP_ENV` is the externally set environment variable. It can be set to `dev` or `prod` to load secrets from either the `dev` vault or the `prod` vault in 1Password. ```shell title="app.env" MYSQL_DATABASE = "op://$APP_ENV/mysql/database" MYSQL_USERNAME = "op://$APP_ENV/mysql/username" MYSQL_PASSWORD = "op://$APP_ENV/mysql/password" ``` **Command line:** You can individually export environment variables as [secret references](/docs/cli/secret-reference-syntax/) from the command line. For example, to set the variable `GITHUB_TOKEN` to a secret reference URI that points to the `personal_token` field within a `credentials` section in a `GitHub` item: **Bash, Zsh, sh:** ```shell export GITHUB_TOKEN=op://development/GitHub/credentials/personal_token ``` **fish:** ```shell set -x GITHUB_TOKEN op://development/GitHub/credentials/personal_token ``` **PowerShell:** ```powershell $Env:GITHUB_TOKEN = "op://development/GitHub/credentials/personal_token" ``` Step 2: Pass the resolved secret references to the application **Environment file:** To use an environment file with `op run`, specify the path to the environment file using the `--env-file` flag: ```shell op run --env-file="./prod.env" -- aws ``` If you structured your environment file to load secrets for multiple environments, make sure to also set the variable for the vault (in the example below, `APP_ENV`). For example, to pass secrets from the `dev` vault to an application running in the development environment: **Bash, Zsh, sh, fish:** ```shell APP_ENV=dev op run --env-file="./app.env" -- myapp deploy ``` **PowerShell:** 1. Set the `$APP_ENV` variable: ```powershell $ENV:APP_ENV = "dev" ``` 2. Run `op run` with the environment file: ```powershell op run --env-file="./app.env" -- myapp deploy ``` **Command line:** If you exported environment variables as secret references on the command line, use `op run --` with the command to start the application or script. 1Password will run the provided command in a subprocess with the secrets made available as environment variables for the duration of the process. ```shell op run -- ``` For example: ```shell op run -- gh ``` :::tip Expand variables in a subshell When you reference a variable like `$MY_VAR` in the same command where you call `op run`, your shell expands `$MY_VAR` before `op run` can substitute the secret reference. For example, a command like the following will pass the secret reference URI instead of the secret value from 1Password: ```shell MY_VAR=op://vault/item/field op run --no-masking -- echo "$MY_VAR" ``` To make sure `op run` substitutes the secret before the variable expands, run the command to expand the variable in a subshell: ```shell MY_VAR=op://vault/item/field op run --no-masking -- sh -c 'echo "$MY_VAR"' #code-result open skdjfs7dyrwhk4jhref ``` ::: :::tip Use both methods together You can load environment variables from an Environment in combination with secret references from a `.env` file or flag. For example: ```shell op run --environment --env-file="./extra-secrets.env" -- ``` ::: ## Next step: Run in production Now that the application works locally, choose how to load your secrets in production or CI/CD: - **[1Password Service Account](/docs/service-accounts/use-with-1password-cli)**: Automate access with a service account token. Service accounts support both secret references and 1Password Environments. - **[1Password Connect Server](/docs/connect/cli/)**: Best for self-hosting within your own infrastructure. Connect only supports secret references and does not currently support 1Password Environments. ## Learn more - [Use 1Password Service Accounts with 1Password CLI](/docs/service-accounts/use-with-1password-cli) - [Use 1Password Connect Server with 1Password CLI](/docs/connect/cli#continuous-integration-ci-environments) - [Load secrets into config files](/docs/cli/secrets-config-files/) - [Secret reference syntax](/docs/cli/secret-reference-syntax/) - [Template syntax](/docs/cli/secrets-template-syntax/) --- ## Load secrets into scripts You can use 1Password CLI to load secrets into your scripts, so that the credentials in your scripts are always in sync with the information in your 1Password account and your secrets are never exposed in plaintext. :::tip We recommend using [1Password Service Accounts](/docs/service-accounts/) to follow the [principle of least privilege](/docs/cli/best-practices/). 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. Service accounts are also useful if your personal account has SSO or MFA requirements. ::: You can use the following methods to load secrets into scripts, separately or in combination: 1. [Use `op run` to pass environment variables from a 1Password Environment](#use-op-run-to-pass-environment-variables-from-a-1password-environment) 2. [Use `op run` to load secrets into the environment.](#option-1-use-op-run-to-load-secrets-into-the-environment) 3. [Use `op read` to read secrets.](#option-2-use-op-read-to-read-secrets) 4. [Use `op inject` to load secrets into a config file.](#option-3-use-op-inject-to-load-secrets-into-a-config-file) 5. [Use `op plugin run` to load secrets using a shell plugin.](#option-4-use-op-plugin-run-to-load-secrets-using-a-shell-plugin) ## Requirements Before you can use 1Password CLI to load secrets into your scripts, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install 1Password CLI.](/docs/cli/get-started#step-1-install-1password-cli) 3. Store the secrets you need for your script in your 1Password account. ## Use `op run` to pass environment variables from a 1Password Environment (Beta) :::note Beta feature To use `op run` with 1Password Environments, you'll need to install the [latest beta build of 1Password CLI](/docs/cli/reference#beta-builds), version `2.33.0-beta.02` or later. ::: You can use [`op run`](/docs/cli/reference/commands/run/) to [pass environment variables](/docs/cli/secrets-environment-variables) stored in a [1Password Environment](/docs/environments) to an application or script at runtime. 1Password CLI runs the application or script in a subprocess with the environment variables stored in your 1Password Environment provisioned for the duration of the process. ## Use `op run` to pass secrets using secret references You can replace the plaintext secrets in your environemnt files with [secret reference URIs](/docs/cli/secret-reference-syntax/) that reference where your project secrets are stored in your 1Password account, then use [`op run`](/docs/cli/reference/commands/run/) to load the corresponding secrets from 1Password and pass them to your script as environment variables at runtime. Learn more about [loading secrets into the environment](/docs/cli/secrets-environment-variables/). ## Use `op read` to read secrets You can use `op read` with secret references [directly in your script](#directly-in-your-script) or [with environment variables](#with-environment-variables). ### Directly in your script With this method, secrets are only passed to the single command that includes the secret reference. For example, to replace your Docker username and password with [secret references](/docs/cli/secret-reference-syntax/) in a command to log in to Docker: ```shell title="yourscript.sh" #!/bin/bash docker login -u "$(op read op://prod/docker/username)" -p "$(op read op://prod/docker/password)" ``` ### With environment variables You can also include a command to set environment variables to `op read` and [secret references](/docs/cli/secret-reference-syntax/) in your script. For example, if you supply an AWS command in your script with secrets using the `AWS_SECRET_ACCESS_KEY` and `AWS_ACCESS_KEY_ID` environment variables, your script might look like this: ```shell title="yourscript.sh" #!/bin/bash export AWS_SECRET_ACCESS_KEY="$(op read op://prod/aws/secret-key)" export AWS_ACCESS_KEY_ID="$(op read op://prod/aws/access-key-id)" aws sts get-caller-identity ``` ## Use `op inject` to load secrets into a config file If your script uses a configuration file, you can template the config file with [secret references](/docs/cli/secret-reference-syntax/), then use [`op inject`](/docs/cli/reference/commands/inject/) to pass the config file with the resolved secrets to your script at runtime. This allows you to check config files into source control and keep them in sync throughout developer workstations, CI, and production servers. And you can include template variables within the secret references to [load different sets of secrets for different environments](/docs/cli/secrets-config-files#step-3-differentiate-between-environments). [Learn how to load secrets into config files](/docs/cli/secrets-config-files/). ## Use `op plugin run` to load secrets using a shell plugin If your script runs interactively and each person using the script authenticates with their own personal token, you can minimize the configuration required in advance of using the script with a [1Password Shell Plugin](/docs/cli/shell-plugins/). Shell plugins prompt each user to select their credentials when the script is executed. Each person using the script will be prompted to configure when their credentials should be used to authenticate. To make sure the credentials they selected will also be used for future invocations of the script, they can configure their credentials as a global or directory default. To use a shell plugin to authenticate an individual command, wrap the command in [`op plugin run`](/docs/cli/reference/management-commands/plugin#plugin-run). For example, to use the AWS shell plugin to provide an AWS Access Key and Secret Key ID to the `sts get-caller-identity` command: ```shell title="yourscript.sh" #!/bin/bash op plugin run -- aws sts get-caller-identity ``` To use a shell plugin throughout a script, you can include an alias for the tool's executable command at the beginning of the script. For example, in this script, the AWS shell plugin would be used to supply secrets for every `aws` command in the script. ```shell title="yourscript.sh" #!/bin/bash alias aws="op plugin run -- aws" aws sts get-caller-identity ``` If a shell plugin doesn't exist for the tool you're using, you can [build a new plugin](/docs/cli/shell-plugins/contribute/). ## Learn more - [Example CLI scripts](/docs/cli/scripts/) - [Get started with secret references](/docs/cli/secret-references/) - [Load secrets into the environment](/docs/cli/secrets-environment-variables/) - [Load secrets into config files](/docs/cli/secrets-config-files/) - [Use 1Password Shell Plugins to securely authenticate third-party CLIs](/docs/cli/shell-plugins/) --- ## 1Password CLI Template Syntax # Template syntax You can create a templated config file that contains [secret references](/docs/cli/secret-reference-syntax/), then [use op inject](/docs/cli/secrets-config-files/) to receive a resolved config file that contains the actual secrets. Here's an example of a template file with enclosed secret references in place of the plaintext secrets: ```yml title="config.yml.tpl" database: host: localhost port: 5432 username: {{ op://prod/database/username }} password: {{ op://prod/database/password }} ``` ## Secret references Secret references included in template files can be formatted as either [unenclosed secret references](#unenclosed-secret-references) or [enclosed secret references](#enclosed-secret-references). ### Unenclosed secret references ```shell op://test-app/database/password ``` An unenclosed secret reference is a string that: - Begins with `op://` and is not preceded by any of the characters from: `alphanumeric`, `-`, `+` , `\`, `.`. - Ends with either the end of the template, or the first encountered character outside the following set: `alphanumeric`, `-`, `?`, `_`, `.`. Examples of good and bad unenclosed secret references: ```yml variant="good" op://prod/docker-credentials/username ``` ```yml variant="good" op://d3v/stripe.keys/s3ct10n/public_key ``` ```yml variant="bad" op://h?ack/1Password!/for"real ``` (contains special characters that are not supported by the syntax) ```yml variant="bad" op://{vault}/[item]/(section)/field ``` (contains special characters that are not supported by the syntax) ### Enclosed secret references ```shell {{ op://test-app/database/password }} ``` An enclosed secret reference is defined as any string that satisifies all of the following: - Begins with two closed braces `{{` - Ends with the two closed braces `}}` - Contains a valid unenclosed secret reference between the two pairs of braces, possibly padded with spaces Examples of good and bad enclosed secret references: ```yml variant="good" {{op://prod/docker-credentials/username}} ``` ```yml variant="good" {{ op://d3v/stripe.keys/s3ct10n/public_key }} ``` ```yml variant="bad" {{op://h?ack/1Password!/for"real}} ``` (the secret reference contains unsupported characters) ### Special characters If you need to escape special characters in your template, you can use curly braces and double quotes: ```yml {{ "{{ test op://prod/docker-credentials/username }}" }} will be resolved to {{ test op://prod/docker-credentials/username }} ``` If the content contains double quotes, they must be escaped with `\`: ```yml {{ "{{ test \"test\" test }}" }} will be resolved to {{ test "test" test }} ``` ## Variables The template syntax also supports variable tags: - `$var` (unenclosed variables) - `${var}` (enclosed variables) When resolving an unenclosed variable of the form `$FOO`, it is replaced with the value of the environment variable named `FOO`. When resolving an enclosed variable of the form `${FOO}`, any whitespace at the beginning or end of `FOO` is discarded and the reference is replaced with the value of the environment variable named `FOO`. Variable names are case-insensitive, cannot start with a number, and can only contain letters, numbers, and underscores. Examples of good and bad unenclosed variables: ```yml variant="good" $my_var ``` ```yml variant="good" $mY_2nd_vAr ``` ```yml variant="bad" $2nd_var ``` (starts with a number) ```yml variant="bad" $var-?notvar! ``` (contains unsupported special characters) Examples of good and bad enclosed variables: ```yml variant="good" ${my_var} ``` ```yml variant="good" ${ mY_2nd_vAr } ``` ```yml variant="bad" ${my_var\} ``` (the closing brace is escaped) ### Default values To set a default value for a template variable, use this syntax: `${VAR_NAME:-}` The default value will be used when the variable can't be found in the environment. For example, `op://${VAULT:-dev}/docker/password` evaluates to `op://dev/docker/password` when the `VAULT` environment variable isn't set. If `VAULT` is set to `prod` instead, it will evaluate to `op://prod/docker/password`. ## Learn more - [Load secrets into config files](/docs/cli/secrets-config-files/) - [Load secrets into the environment](/docs/cli/secrets-environment-variables/) - [Secret reference syntax](/docs/cli/secret-reference-syntax/) --- ## Use 1Password to authenticate the Akamai CLI with biometrics # Use 1Password to securely authenticate the Akamai CLI The Akamai CLI shell plugin allows you to use 1Password to securely authenticate [the Akamai CLI ](https://techdocs.akamai.com/developer/docs/about-clis) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Akamai CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.13.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Akamai CLI. ](https://techdocs.akamai.com/developer/docs/about-clis) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with Akamai by injecting a temporary config file with the credentials required by the plugin commands directly from your 1Password account. If you saved your Akamai CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | `.edgerc` field | | --- | --- | | Client Secret | `client_secret` | | Host | `host` | | Access Token | `access_token` | | Client Token | `Client_token` | *Thanks to [@wongle](https://github.com/wongle) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/234)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate Argo CD CLI with biometrics # Use 1Password to securely authenticate Argo CD CLI The Argo CD shell plugin allows you to use 1Password to securely authenticate [Argo CD CLI ](https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Argo CD CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.13.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Argo CD CLI ](https://argo-cd.readthedocs.io/en/stable/cli_installation/). The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | AuthToken | `ARGOCD_AUTH_TOKEN` | | Address (optional) | `ARGOCD_SERVER` | *Thanks to [@ssttehrani](https://github.com/ssttehrani) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/145)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the AWS CDK Toolkit # Use 1Password to securely authenticate the AWS CDK Toolkit The AWS CDK Toolkit shell plugin allows you to use 1Password to securely authenticate the [AWS CDK Toolkit ](https://docs.aws.amazon.com/cdk/v2/guide/cli.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the AWS CDK Toolkit with biometrics. You can also set up the [AWS CLI shell plugin](/docs/cli/shell-plugins/aws/). ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install the AWS CDK Toolkit ](https://docs.aws.amazon.com/cdk/v2/guide/cli.html). 6. Make sure you have an AWS config file at `~/.aws/config` on Mac or Linux, or `C:\Users\USERNAME\.aws\config` on Windows. If you don't have a config file, use [`aws configure` ](https://docs.aws.amazon.com/cli/latest/reference/configure/) to create one. When prompted, skip entering your AWS access key pair to avoid writing your credentials on disk in the `.aws/credetials` file. The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | --- | --- | | Access Key ID | `AWS_ACCESS_KEY_ID` | | Secret Access Key | `AWS_SECRET_ACCESS_KEY` | | Default region (optional) | `AWS_DEFAULT_REGION` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the AWS CLI with biometrics # Use 1Password to securely authenticate the AWS CLI The AWS shell plugin allows you to use 1Password to securely authenticate [the AWS CLI ](https://aws.amazon.com/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the AWS CLI with biometrics. If you use `cdk`, you can also set up the [AWS CDK Toolkit shell plugin](/docs/cli/shell-plugins/aws-cdk-toolkit/). ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the AWS CLI. ](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) After you install the AWS CLI, make sure you have an AWS config file at `~/.aws/config` on Mac or Linux, or `C:\Users\USERNAME\.aws\config` on Windows. If you don't have a config file: 1. Use [`aws configure` ](https://docs.aws.amazon.com/cli/latest/reference/configure/) to create one. 2. When prompted, skip entering your AWS access key pair to avoid writing your credentials on disk in the `.aws/credetials` file. The following shells are supported: - Bash - Zsh - fish ## Before you begin: Create and save an AWS access key If you've already created an AWS access key, [skip to step 1](#step-1-configure-your-default-credentials). If you haven't created an access key yet, you can create one and use the [1Password browser extension](https://support.1password.com/getting-started-browser/) to quickly save it in 1Password: 1. Open and unlock [1Password in your browser](https://support.1password.com/getting-started-browser/). 2. [Follow the steps](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html?icmpid=docs_iam_console#Using_CreateAccessKey) to create an access key for the AWS CLI. 3. On the "Retrieve access keys" page, select **Show** to reveal the secret access key. 4. Select **Save item** when 1Password asks if you want to save an item for the AWS access key. 5. Choose the vault where you want to save the item, edit the item's name and details, then select **Save item**. _[The pop-up screen to save your AWS access key in 1Password.]_ ## Step 1: Configure your default credentials :::tip If you use AWS in multiple environments If you want to use the AWS shell plugin in multiple environments, like production and development, [learn how to set up your plugin for seamless context switching](/docs/cli/shell-plugins/environments/). ::: To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After you save your AWS credentials in 1Password, you can remove all local copies you currently have stored on disk. Plaintext access keys are commonly stored in your AWS [shared credentials file ](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/creds-file.html) (default location: `~/.aws/credentials`). If you remove your credentials from this file, make sure to configure shell plugins for any other tools that use the file to authenticate to AWS, like [Terraform](/docs/cli/shell-plugins/terraform/). ## Optional: Assume multiple roles You can use the AWS shell plugin to assume multiple roles in the same way you'd assume roles with the AWS CLI, by defining role profiles [in your AWS config file. ](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-role-prepare) For example: ```html title="~/.aws/config" [profile prod] role_arn = arn:aws:iam::123456789012:role/prod source_profile = wendyappleseed ``` Then include the `--profile` flag to call an AWS command using a role. For example: ```shell aws sts get-caller-identity --profile prod ``` If you want to always use the same profile, you can set the `AWS_PROFILE` environment variable. In that case, the `--profile` flag would only be needed to override the default set in the environment. For example: ```shell export AWS_PROFILE=prod ``` ## Optional: Set up multi-factor authentication If you use [multi-factor authentication ](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html) with AWS, you can configure the AWS shell plugin to provide your one-time password. You can do this in two ways: - [Add the ARN for your multi-factor authentication device to a profile in your AWS config file. ](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-mfa) - Add the one-time password code and ARN to the item in 1Password where your AWS credentials are stored. If you choose this option, your multi-factor authentication information will be treated as your `default` profile and used globally with every other profile. Save your one-time password and ARN in 1Password Step 1: Save your QR code 2. Open and unlock the 1Password app. 3. Select the item where your AWS credentials are saved, then select **Edit**. 4. Select **Add More** > **One-Time Password**. 5. [Follow the steps to enable a virtual multi-factor authentication device](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_enable_virtual.html) for your AWS account. 5. Select **Show secret key** in the AWS wizard, then copy the string of characters into the One-Time Password field on your item. 6. Select **Save**. Your item will now show a one-time password that you can use to finish the AWS multi-factor authentication device set-up flow. Your edited item must include the `one-time password` and `mfa serial` fields: _[The AWS item in 1Password with MFA credentials added.]_ Step 2: Save the ARN for your multi-factor authentication device 1. Find the [ARN for your multi-factor authentication device](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_checking-status.html) and copy it. 3. Open and unlock the 1Password app. 4. Select the item where you saved your AWS credentials then select **Edit**. 5. Select **Add More** > **Text**. 6. Paste the ARN as the value of the field. 7. Title the field `mfa serial`. 8. Select **Save**. 1Password CLI will detect your multi-factor authentication credentials if they're saved in fields titled `one-time password` and `mfa serial`. If your one-time password isn't detected, make sure your fields are titled correctly. 1Password CLI will then set the `AWS_SECRET_ACCESS_KEY`, `AWS_ACCESS_KEY_ID` and `AWS_SESSION_TOKEN` provisional environment variables to specify the temporary multi-factor authentication session values. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | --- | --- | | Access Key ID | `AWS_ACCESS_KEY_ID` | | Secret Access Key | `AWS_SECRET_ACCESS_KEY` | | Default region (optional) | `AWS_DEFAULT_REGION` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to securely authenticate Axiom CLI The Axiom CLI shell plugin allows you to use 1Password to securely authenticate [Axiom CLI ](https://axiom.co/docs/reference/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Axiom CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.x.x or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Axiom CLI. ](https://axiom.co/docs/reference/cli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `AXIOM_TOKEN` | | Organization | `AXIOM_ORG_ID` | | Deployment | `AXIOM_DEPLOYMENT` | *Thanks to [@rajapri28613](https://github.com/rajapri28613) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/342)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to securely authenticate Binance CLI The Binance shell plugin allows you to use 1Password to securely authenticate [Binance CLI ](https://github.com/binance/binance-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Binance CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Binance CLI. ](https://github.com/binance/binance-cli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | API Key | `BINANCE_API_KEY` | | API Secret | `BINANCE_API_SECRET` | *Thanks to [@bala-ceg](https://github.com/bala-ceg) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/391)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to authenticate the Cachix CLI with biometrics # Use 1Password to securely authenticate the Cachix CLI The Cachix shell plugin allows you to use 1Password to securely authenticate [the Cachix CLI ](https://docs.cachix.org) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Cachix CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.11.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Cachix CLI. ](https://github.com/cachix/cachix#installation) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `CACHIX_AUTH_TOKEN` | *Thanks to [@micnncim](https://github.com/micnncim) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/97)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate Cargo CLI with biometrics # Use 1Password to securely authenticate Cargo CLI The Cargo CLI shell plugin allows you to use 1Password to securely authenticate [Cargo CLI ](https://crates.io/crates/cargo-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Cargo CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.13.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Cargo CLI. ](https://crates.io/crates/cargo-cli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `CARGO_REGISTRY_TOKEN` | *Thanks to [@accraw](https://github.com/accraw) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/139)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the CircleCI CLI with biometrics # Use 1Password to securely authenticate the CircleCI CLI The CircleCI shell plugin allows you to use 1Password to securely authenticate [the CircleCI CLI ](https://circleci-public.github.io/circleci-cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the CircleCI CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the CircleCI CLI. ](https://circleci.com/docs/local-cli#installation) The following shells are supported: - Bash - Zsh - fish ## Before you begin: Create and save a CircleCI personal API token If you've already created a CircleCI personal API token, [skip to step 1](#step-1-configure-your-default-credentials). If you haven't created a personal API token yet, you can create one and use the [1Password browser extension](https://support.1password.com/getting-started-browser/) to quickly save it in 1Password: 1. Open and unlock [1Password in your browser](https://support.1password.com/getting-started-browser/). 2. [Follow the steps](https://circleci.com/docs/managing-api-tokens#creating-a-personal-api-token) to create a CircleCI personal API token. 3. Select **Save item** when 1Password asks if you want to save an item for the CircleCI personal API token. 4. Choose the vault where you want to save the item, edit the item's name and details, then select **Save item**. _[The prompt to save your CircleCI personal API token in 1Password.]_ ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `CIRCLECI_CLI_TOKEN` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to securely authenticate Civo CLI The Civo CLI shell plugin allows you to use 1Password to securely authenticate [Civo CLI ](https://www.civo.com/docs/overview/civo-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Civo CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Civo CLI. ](https://www.civo.com/docs/overview/civo-cli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | API Key | `CIVO_API_KEY` | | API Key ID | `CIVO_API_KEY_NAME` | *Thanks to [@siddhikhapare](https://github.com/siddhikhapare) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/325)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to authenticate Wrangler with biometrics # Use 1Password to securely authenticate the Cloudflare Workers CLI The Cloudflare Workers shell plugin allows you to use 1Password to securely authenticate [Wrangler ](https://developers.cloudflare.com/workers/wrangler/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Wrangler with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.12.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Wrangler. ](https://developers.cloudflare.com/workers/wrangler/install-and-update/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Account ID (Optional) | `CLOUDFLARE_ACCOUNT_ID` | | Token | `CLOUDFLARE_API_TOKEN` | *Thanks to [@shyim](https://github.com/shyim) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/94)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Build your own shell plugins (beta) If you don't see your favorite command-line tool [listed in the 1Password Shell Plugin registry](/docs/cli/shell-plugins/), you can write your own plugin. 1Password CLI allows you to build and test shell plugins locally, so you can add support for authenticating your favorite CLI using a credential you saved in 1Password. If you want to make your plugin available to others, you can [create a pull request in the shell plugins GitHub repository](https://github.com/1Password/shell-plugins). ## Requirements - [Sign up for 1Password](https://1password.com/pricing/password-manager). - Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). - Install [1Password CLI](/docs/cli/get-started/) and turn on the [desktop app integration](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). - Install [Go 1.18 or later](https://go.dev/doc/install). - Install [Git](https://git-scm.com/). - Install [GNU Make](https://www.gnu.org/software/make/). ## Concepts A 1Password Shell Plugin should describe the following: - The **credential** offered by a platform - The CLI or **executable** offered by a platform - How the credential should be **provisioned** for the respective CLI to authenticate - Which commands for the respective CLI **need authentication** - How credentials stored on the local filesystem can be **imported** into 1Password Shell plugins are written in Go and consist of a set of Go structs in a package that together make up the plugin for a certain platform, service, or product. Don't worry if you're not a Go expert – there are [lots of examples](https://github.com/1Password/shell-plugins/tree/main/plugins) you can learn from to build your plugin! ## Step 1: Use the plugin template First, clone or fork the [1Password Shell Plugins repository](https://github.com/1Password/shell-plugins) on GitHub. It contains the current plugin registry, as well as the SDK needed to contribute. To get started with those, use the following Makefile command: ```shell make new-plugin ``` You'll be prompted to enter the following information: - **Plugin name:** Lowercase identifier for the platform, e.g. `aws`, `github`, `digitalocean`, `azure`. This will also be used as the name of the Go package. - **Plaform display name:** The display name of the platform, e.g `AWS`, `GitHub`, `DigitalOcean`, `Azure`. - **Credential name:** The credentials the platform offers, e.g. `Personal Access Token`, `API Key`, `Auth Token`. - **Executable name:** The command to invoke, e.g. `aws`, `gh`, `doctl`, `az`. After filling in the form, you'll see a Go package created in the `plugins` directory, with separate files for the plugin, credential, and executable. For example: ``` plugins/ ├── aws/ │ ├── plugin.go │ ├── access_key.go │ └── aws.go ├── digitalocean/ │ ├── plugin.go │ ├── personal_access_token.go │ └── doctl.go ├── github/ │ ├── plugin.go │ ├── personal_access_token.go │ └── gh.go └── heroku/ ├── plugin.go ├── api_key.go └── heroku.go ``` To save you some time, the generated files will be stubbed out with information that's derived from the Makefile prompts on a best-effort basis. It contains *TODO* comments in the code to steer you in the direction of what to change or validate for correctness. ## Step 2: Edit the plugin definition The `plugin.go` file contains basic information about the plugin and the platform it represents, including which credential types and executables make up the plugin. > **Tip** > } title="Plugin Examples"> - [AWS](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/plugin.go) - [GitHub](https://github.com/1Password/shell-plugins/blob/main/plugins/github/plugin.go) - [Heroku](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/plugin.go) ## Step 3: Edit the credential definition The credential definition file describes the schema of the credential, how the credential should get provisioned to executables, and how the credential can be imported into 1Password. > **Tip** > } title="Credential Examples"> - [AWS Access Key](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/access_key.go) - [GitHub Personal Access Token](https://github.com/1Password/shell-plugins/blob/main/plugins/github/personal_access_token.go) - [Heroku API Key](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/api_key.go) ### Credential information and schema The first section of the credential definition is where you can add information about the credential: - The **name** of the credential, as the platform calls it. - The **documentation URL** provided by the platform that describes the credential. *(optional)* - The **management URL** on the platform where the credential can be created and revoked. This is usually a URL to the dashboard, console, or authentication settings of the platform. *(optional)* The next section is where you define the schema of the credential. This is segmented into fields. Many credentials consist of just a single secret field, but you can add more fields to add more details to the 1Password item that are related to authentication, even if the fields are not secret. Examples of additional fields are: the host, username, account ID, and all other things that are needed to authenticate and make sense to include in the 1Password item for the credential type. All fields you declare here will also show up in the end user's 1Password item. Here's what you can specify per **field**: - The **field name**, titlecased. *(required)* - A short **description** of the field. This supports markdown. *(required)* - Whether the field is **optional**. Defaults to false. - Whether the field is **secret**, and should be concealed in the 1Password GUI. Defaults to not secret. Note: The credential schema is expected to contain at least 1 secret field. - What the actual credential **value is composed of**. The length, character set, and whether it contains a fixed prefix. ### Provisioner The credential definition also specifies how the credential is usually provisioned to exectuables, in order for them to use the credential for authentication. Provisioners are in essence hooks that get executed before the executable is run by 1Password CLI, and after the executable exits in case any cleanup is needed. In those hooks, provisioners can do all the setup required for the executable to authenticate, including setting environment variables, creating files, adding command-line arguments, or even generating temporary credentials. After the executable exits, there should be no trace of the credentials on the user's filesystem. The SDK provides a few common provisioners out of the box, so in most cases you don't have to care about the provisioning internals. **Environment variables:** We currently recommend using environment variables as your provisioning method. Environment variables are the most ubiquitous way to provision secrets. They only live in memory, and almost every CLI allows you to authenticate with them. Here's how you can use the environment variable provisioner provided by the SDK: ```go provision.EnvVars(map[string]sdk.FieldName{ "AWS_ACCESS_KEY_ID": fieldname.AccessKeyID, "AWS_SECRET_ACCESS_KEY": fieldname.SecretAccessKey, }) ``` Specify the 1Password field name and the environment variable name it should be placed in. To figure out what environment variable the underlying CLI reads, here are a few tips: - Search the platform's CLI documentation website for a getting started guide, authentication guide, or CLI reference docs. - Look at the CLI's help text or manpage. - If the CLI or the underlying SDK it uses is open source, scan the source code to see if it accepts environment variables for authentication. **Files:** Some CLIs only support reading credentials from files on disk. In that case, you can use the file provisioner provided by the SDK. The file provisioner takes care of creating the file in a temporary directory and deleting it afterwards. For security purposes, the file created by the file provisioner can only be read **once** by the executable. If that limitation does not work for your use case, you can file an [issue on GitHub](https://github.com/1Password/shell-plugins/issues). Here are a few examples on how you can use the file provisioner to provision a temporary JSON file and pass the generated path to the executable: ```go title="Create a file provisioner and pass output path as --config-file" provision.TempFile(configFile, provision.Filename("config.json"), provision.AddArgs("--config-file", "{{ .Path }}"), ) ``` ```go title="Create a file provisioner and set output path as CONFIG_FILE_PATH" provision.TempFile(configFile, provision.Filename("config.json"), provision.SetPathAsEnvVar("CONFIG_FILE_PATH"), ) ``` ```go title="Create a file provisioner and pass output path as Java property" provision.TempFile(configFile, provision.Filename("config.json"), provision.AddArgs(`-Dconfig.path="{{ .Path }}"`), ) ``` ```go title="Code to generate JSON file contents" func configFile(in sdk.ProvisionInput) ([]byte, error) { config := Config{ Token: in.ItemFields[fieldname.Token] } contents, err := json.Marshal(config) if err != nil { return nil, err } return []byte(contents), nil } type Config struct { Token string `json:"token"` } ``` **Other:** If the standard provisioners included in the SDK are not enough to authenticate the executable, you can also write your own provisioner. You can do so by implementing the [`sdk.Provisioner` interface](https://github.com/1Password/shell-plugins/blob/main/sdk/provisioner.go). A good example of a custom provisioner is the [AWS STS provisioner](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/sts_provisioner.go) that generates temporary credentials based on a one-time password code loaded from 1Password. ### Importer The credential definition also lets you specify importers. Importers are responsible for scanning the user's environment and file system for any occurrences of the needed credentials. 1Password CLI will run the importer and prompt the user to import their credentials one by one into 1Password. It's very common for CLIs to write authentication data to disk, most commonly in a hidden config file in your home directory. This is not always documented by the CLI, so here are some tips to figure out if such a config file exists: - Check the platform's documentation for mentions of config files. - See if the CLI offers a `login`, `auth`, `configure`, or `setup` command that covers authentication. If it does, it's pretty likely there's a credential being stored in your home directory after completing such a flow. - If the CLI is open source, check the source code to see if such a file exists. - Look at your own home directory or `~/.config` directory to see if there are files related to the platform. Here's an example command to find local `aws` configuration files: ```shell find ~/.* -maxdepth 3 -path "*aws*" ``` The SDK provides helper functions to load files, parse files, and scan environment variables to make writing an importer for your credential type easier. > **Tip** > } title="Importer Examples"> - [AWS Access Key](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/access_key.go) (`~/.aws/credentials`) - [CircleCI Personal API Token](https://github.com/1Password/shell-plugins/blob/main/plugins/circleci/personal_api_token.go) (`~/.circleci/cli.yml`) - [Heroku API Key](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/api_key.go) (`~/.netrc`) If you already have a shell plugin configured for a tool, and you want to generate an example configuration tile to test an importer, reference the tool by its full path rather than by its name. This makes sure you invoke the the tool without the plugin. ## Step 4: Edit the executable definition The last thing the plugin is responsible for is to define the CLI or executable that you'd like 1Password to handle authentication for. This is the final piece that glues everything together. The executable definition describes the following: - The **command** that should get executed by the 1Password CLI. - The display **name** of the CLI, as the platform calls it. - The **documentation URL** provided by the platform that describes the executable. *(optional)* - When the executable **needs authentication**. For example, many CLIs don't require authentication when the `--help` or `--version` flags are present. - The **credentials** that the executable uses. > **Tip** > } title="Executable Examples"> - [AWS CLI](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/aws.go) (`aws`) - [GitHub CLI](https://github.com/1Password/shell-plugins/blob/main/plugins/github/gh.go) (`gh`) - [Heroku CLI](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/heroku.go) (`heroku`) ## Step 5: Build and test your plugin locally To see if you've properly filled out the plugin, credential, and executable defintions, you can run the following Makefile command to validate the definitions: ``` make /validate ``` If that succeeds, it's now time to locally build and test your plugin! You can do so using the following command: ``` make /build ``` The build artifact will be placed in `~/.op/plugins/local`. It should show up in `op` if you run the following command: ```shell op plugin list ``` To see it in action, you can use the `op plugin init` command: ```shell op plugin init ``` ## Submit a PR While you're free to keep on using the plugin locally, we'd encourage you to submit a PR on the [main registry on GitHub](https://github.com/1Password/shell-plugins) so others can use it too! Before doing so, be sure to read the [CONTRIBUTING.md](https://github.com/1Password/shell-plugins/blob/main/CONTRIBUTING.md) file on GitHub. If you feel that the SDK does not serve your use case well, reach out to us by creating an [issue on GitHub](https://github.com/1Password/shell-plugins/issues) or by joining our [Developer Slack workspace](https://developer.1password.com/joinslack) to tell us about your plugin proposal. We can advise you on the most suitable approach for your use case. ## Learn more - [Shell plugins troubleshooting](/docs/cli/shell-plugins/troubleshooting/) - [Join our Developer Slack workspace](https://developer.1password.com/joinslack) --- ## Use 1Password to securely authenticate Crowdin CLI The Crowdin CLI shell plugin allows you to use 1Password to securely authenticate [Crowdin CLI ](https://crowdin.github.io/crowdin-cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Crowdin CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Crowdin CLI. ](https://crowdin.github.io/crowdin-cli/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `CROWDIN_PERSONAL_TOKEN` | | Project ID | `CROWDIN_PROJECT_ID` | | Host Address | `CROWDIN_BASE_URL` | *Thanks to [@JoeKarow](https://github.com/JoeKarow) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/359)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to authenticate Databricks CLI with biometrics # Use 1Password to securely authenticate Databricks CLI The Databricks shell plugin allows you to use 1Password to securely authenticate [Databricks CLI ](https://docs.databricks.com/dev-tools/cli/index.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Databricks CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.13.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Databricks CLI. ](https://docs.databricks.com/dev-tools/cli/index.html) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Host | `DATABRICKS_HOST` | | Token | `DATABRICKS_TOKEN` | *Thanks to [@bsamseth](https://github.com/bsamseth) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/143)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate Dogshell with biometrics # Use 1Password to securely authenticate Dogshell The Dogshell shell plugin allows you to use 1Password to securely authenticate [Dogshell ](https://docs.datadoghq.com/developers/guide/dogshell-quickly-use-datadog-s-api-from-terminal-shell/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Dogshell with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Dogshell. ](https://docs.datadoghq.com/developers/guide/dogshell-quickly-use-datadog-s-api-from-terminal-shell/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | --- | --- | | API Key | `DATADOG_API_KEY` | | App Key | `DATADOG_APP_KEY` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate doctl with biometrics # Use 1Password to securely authenticate the DigitalOcean CLI The DigitalOcean shell plugin allows you to use 1Password to securely authenticate [doctl ](https://docs.digitalocean.com/reference/doctl/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate doctl with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [doctl. ](https://docs.digitalocean.com/reference/doctl/how-to/install/) The following shells are supported: - Bash - Zsh - fish ## Before you begin: Create and save a DigitalOcean personal access token If you've already created a DigitalOcean personal access token, [skip to step 1](#step-1-configure-your-default-credentials). If you haven't created a personal access token yet, you can create one and use the [1Password browser extension](https://support.1password.com/getting-started-browser/) to quickly save it in 1Password: 1. Open and unlock [1Password in your browser](https://support.1password.com/getting-started-browser/). 2. [Follow the steps](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to create a DigitalOcean personal access token. 3. Select **Save item** when 1Password asks if you want to save an item for the DigitalOcean personal access token. 4. Choose the vault where you want to save the item, edit the item's name and details, then select **Save item**. _[The prompt to save your DigitalOcean personal access token in 1Password.]_ ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `DIGITALOCEAN_ACCESS_TOKEN` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password Shell Plugins to switch between multiple environments # Use shell plugins to switch between multiple environments You can use [1Password Shell Plugins](/docs/cli/shell-plugins/) to seamlessly switch between different sets of credentials for different environments, so you don't have to spend time signing in or out between environments. For example, you can set the Terraform shell plugin to use your development credentials in the working directory for your development environment and your production credentials in the working directory for your production environment. Then when you run a Terraform command in either directory, the Terraform plugin will automatically authenticate with the appropriate credentials. ## Step 1: Organize your directories by environment Before you configure a shell plugin for context switching between environments, group the directories you want to use with the plugin by environment. For example, if you wanted to use the Terraform shell plugin in both development and production environments, you would organize your directories like this: ``` projects/ ├─ development/ │ ├─ dev-project-1 │ ├─ dev-project-2 ├─ production/ │ ├─ prod-project-1 │ ├─ prod-project-2 ``` ## Step 2: Configure default credentials for each environment After you organize your directories by environment, you can set default credentials for your shell plugin to use in each directory and all its subfolders. 1. Change directories to one of the environment-level folders you created. For example: ```shell cd projects/production ``` 2. Sign in to the 1Password account where the credentials you want to use are stored: ```shell op signin ``` 3. Choose a plugin to initialize, or run `op plugin init` to choose from a list of all available plugins. For example, to initialize the Terraform shell plugin: ```shell op plugin init terraform ``` 4. Import or select the appropriate credentials for the environment. 5. Select **Use automatically when in this directory or subdirectories** as the default credential scope. 6. Repeat the process in other environment-level folders with their respective credentials. This will make the credentials you configure in each environment-level folder the default for all subfolders within it, as long as no other directory-specific defaults are set in them. ## Step 3: Use the plugin in multiple environments After you set default credentials in all your environment-level folders, you can use the shell plugin in the working directories for each environment without needing to sign in or out. 1. Enter the working directory for an environment. For example, to change directories into the development environment from the example above: ```shell cd ~/projects/development 2. Run a job in that environment. For example: ```shell terraform apply ``` 3. Switch to a different environment. For example, to change to the production environment: ```shell cd ~/projects/production ``` 4. Run a job in that environment: ```shell terraform apply ``` 5. Exit the environment: ```shell op signout ``` The shell plugin will automatically authenticate with the appropriate credentials for each environment, without requiring any action on your part. ## Learn more - [Get started with 1Password Shell Plugins](/docs/cli/shell-plugins/) - [Build your own shell plugins](/docs/cli/shell-plugins/contribute/) --- ## Use 1Password to authenticate Fastly CLI with biometrics # Use 1Password to securely authenticate Fastly CLI The Fastly shell plugin allows you to use 1Password to securely authenticate [Fastly CLI ](https://developer.fastly.com/reference/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Fastly CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.14.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Fastly CLI. ](https://developer.fastly.com/learning/tools/cli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `FASTLY_API_TOKEN` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/169)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to securely authenticate Flyctl The Flyctl shell plugin allows you to use 1Password to securely authenticate [Flyctl ](https://fly.io/docs/hands-on/install-flyctl/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Flyctl with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Flyctl. ](https://fly.io/docs/hands-on/install-flyctl/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `FLY_ACCESS_TOKEN` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/141)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to authenticate FOSSA CLI with biometrics # Use 1Password to securely authenticate FOSSA CLI The FOSSA shell plugin allows you to use 1Password to securely authenticate [FOSSA CLI ](https://github.com/fossas/fossa-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate FOSSA CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [FOSSA CLI. ](https://github.com/fossas/fossa-cli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | API Key | `FOSSA_API_KEY` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Gitea CLI with biometrics # Use 1Password to securely authenticate the Gitea CLI The Gitea shell plugin allows you to use 1Password to securely authenticate [the Gitea CLI ](https://gitea.com/gitea/tea) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Gitea with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.16.1 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install the Gitea CLI ](https://gitea.com/gitea/tea). The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ```shell rm ~/.config/tea/config.yml ``` ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with Gitea by injecting a temporary file with the credentials required by the plugin commands directly from your 1Password account. If you saved your Gitea credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | YAML config field | | --- | --- | | Token | `token` | | HostAddress | `name`, `url` | | User | `user` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the GitHub CLI with biometrics # Use 1Password to securely authenticate the GitHub CLI The GitHub shell plugin allows you to use 1Password to securely authenticate [the GitHub CLI ](https://cli.github.com/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the GitHub CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the GitHub CLI ](https://github.com/cli/cli#installation). The following shells are supported: - Bash - Zsh - fish ## Before you begin: Create and save a GitHub personal access token Before you can use 1Password to authenticate the GitHub CLI, you'll need to [create a GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). 1Password authenticates the GitHub CLI with your personal access token instead of a username and password. If you've already created a personal access token, [skip to step 1](#step-1-configure-your-default-credentials). If you haven't created a personal access token yet, you can create one and use the [1Password browser extension](https://support.1password.com/getting-started-browser/) to quickly save it in 1Password: 1. Open and unlock [1Password in your browser](https://support.1password.com/getting-started-browser/). 2. [Follow the steps](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to create a GitHub personal access token. 3. Select **Save item** when 1Password asks if you want to save an item for the GitHub personal access token. 5. Choose the vault where you want to save the item, edit the item's name and details, then select **Save item**. _[The pop-up screen to save your GitHub personal access token in 1Password.]_ ## Step 1: Configure your default credentials :::tip If you use multiple GitHub accounts If you want to use the GitHub shell plugin with more than one GitHub account, like your personal and work accounts, [learn how to set up your plugin to use multiple accounts](/docs/cli/shell-plugins/multiple-accounts/). ::: To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. If you use a single GitHub account, select **Use as global default on my system**. This will set your personal access token as the default in all terminal sessions and directories. If you use multiple GitHub accounts, [learn how to use directory-specific defaults for context switching](/docs/cli/shell-plugins/multiple-accounts/). ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your GitHub credentials in 1Password, you can remove all local copies you previously had stored on disk. ```shell rm ~/.config/gh/hosts.yml ``` ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | --- | --- | | Token | `GH_TOKEN` | | Host (optional) | `GH_HOST` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the GitLab CLI with biometrics # Use 1Password to securely authenticate the GitLab CLI The GitLab shell plugin allows you to use 1Password to securely authenticate [the GitLab CLI ](https://docs.gitlab.com/ee/integration/glab/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the GitLab CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the GitLab CLI. ](https://gitlab.com/gitlab-org/cli/-/blob/main/README.md#installation) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Optional: If you use a self-hosted instance, set the host If you use a self-hosted GitLab instance, you'll need to add your host URL to the GitLab item you configured in the previous step. Save the URL in a custom text field titled `Host` to make it available to the shell plugin. **1Password CLI:** To add the field using 1Password CLI: **Bash, Zsh, sh, fish:** ```shell op item edit \ 'Host[text]=https://gitlab.yourdomain.com' ``` **PowerShell:** ```powershell op item edit ` 'Host[text]=https://gitlab.yourdomain.com' ``` **1Password desktop app:** To add the field using the 1Password desktop app: 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Navigate to the item you configured in the previous step and select **Edit**. 3. Select **Add More** > **Text** to add a custom text field. 4. Select the default field name, "text", and rename it to `Host`. 5. Enter your GitLab host as the field value. For example, `https://gitlab.yourdomain.com` 6. Select **Save**. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | --- | --- | | Token | `GITLAB_TOKEN` | | Host (optional; required for self-hosted instances) | `GITLAB_HOST` | | API Host (optional) | `GITLAB_API_HOST` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Vault CLI with biometrics # Use 1Password to securely authenticate the HashiCorp Vault CLI The HashiCorp Vault shell plugin allows you to use 1Password to securely authenticate [the Vault CLI ](https://developer.hashicorp.com/vault/docs/commands) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Vault CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Vault CLI. ](https://developer.hashicorp.com/vault/tutorials/getting-started/getting-started-install) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | --- | --- | | Token | `VAULT_TOKEN` | | Address (optional) | `VAULT_ADDR` | | Namespace (optional) | `VAULT_NAMESPACE` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Heroku CLI with biometrics # Use 1Password to securely authenticate the Heroku CLI The Heroku shell plugin allows you to use 1Password to securely authenticate [the Heroku CLI ](https://devcenter.heroku.com/articles/heroku-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Heroku CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Heroku CLI. ](https://devcenter.heroku.com/articles/heroku-cli#install-the-heroku-cli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | API Key | `HEROKU_API_KEY` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate hcloud with biometrics # Use 1Password to securely authenticate the Hetzner Cloud CLI The Hetzner Cloud shell plugin allows you to use 1Password to securely authenticate [hcloud ](https://github.com/hetznercloud/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate hcloud with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.12.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [hcloud. ](https://github.com/hetznercloud/cli#installation) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | --- | --- | | Token | `HCLOUD_TOKEN` | *Thanks to [@shyim](https://github.com/shyim) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/87)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate brew with biometrics # Use 1Password to securely authenticate brew The Homebrew shell plugin allows you to use 1Password to securely authenticate [the Homebrew package manager ](https://brew.sh/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate brew with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.11.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [brew. ](https://brew.sh/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `HOMEBREW_GITHUB_API_TOKEN` | *Thanks to [@markdorison](https://github.com/markdorison) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/110)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to securely authenticate HuggingFace CLI The HuggingFace CLI shell plugin allows you to use 1Password to securely authenticate [HuggingFace CLI ](https://huggingface.co/docs/huggingface_hub/quick-start) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate HuggingFace CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install HuggingFace CLI. ](https://huggingface.co/docs/huggingface_hub/quick-start) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | User Access Token | `HUGGING_FACE_HUB_TOKEN` | | Endpoint (optional) | `HF_ENDPOINT` | | API URL (optional) | `HF_INFERENCE_ENDPOINT` | *Thanks to [@bala-ceg](https://github.com/bala-ceg) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/393)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to securely authenticate InfluxDB The InfluxDB shell plugin allows you to use 1Password to securely authenticate [InfluxDB ](https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/config/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate InfluxDB with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install InfluxDB. ](https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/config/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Host | `INFLUX_HOST` | | Organization | `INFLUX_ORG` | | Access Token | `INFLUX_TOKEN` | *Thanks to [@bala-ceg](https://github.com/bala-ceg) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/392)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to securely authenticate Kaggle CLI The Kaggle CLI shell plugin allows you to use 1Password to securely authenticate [Kaggle CLI ](https://github.com/Kaggle/kaggle-api) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Kaggle CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Kaggle CLI. ](https://github.com/Kaggle/kaggle-api) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `KAGGLE_KEY` | | Username | `KAGGLE_USERNAME` | *Thanks to [@rajapri28613](https://github.com/rajapri28613) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/341)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to authenticate the Lacework CLI with biometrics # Use 1Password to securely authenticate the Lacework CLI The Lacework shell plugin allows you to use 1Password to securely authenticate [the Lacework CLI ](https://docs.lacework.com/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Lacework CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.10.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Lacework CLI. ](https://docs.lacework.com/cli/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Account | `LW_ACCOUNT` | | API Key ID | `LW_API_KEY` | | API Secret | `LW_API_SECRET` | *Thanks to [@colinbarr](https://github.com/colinbarr) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/95)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Laravel Forge CLI with biometrics # Use 1Password to securely authenticate the Laravel Forge CLI The Laravel Forge shell plugin allows you to use 1Password to securely authenticate [the Laravel Forge CLI ](https://forge.laravel.com/docs/1.0/cli.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Laravel Forge CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Laravel Forge CLI ](https://forge.laravel.com/docs/1.0/cli.html#installation). The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `FORGE_API_TOKEN` | *Thanks to [@andresayej](https://github.com/andresayej) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/244)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Laravel Vapor CLI with biometrics # Use 1Password to securely authenticate the Laravel Vapor CLI The Laravel Vapor shell plugin allows you to use 1Password to securely authenticate [the Laravel Vapor CLI ](https://docs.vapor.build/1.0/introduction.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Laravel Vapor CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Laravel Vapor CLI ](https://docs.vapor.build/1.0/introduction.html#installing-the-vapor-cli). The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `VAPOR_API_TOKEN` | *Thanks to [@andresayej](https://github.com/andresayej) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/245)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Linode CLI with biometrics # Use 1Password to securely authenticate the Linode CLI The Linode shell plugin allows you to use 1Password to securely authenticate [the Linode CLI ](https://www.linode.com/docs/products/tools/cli/get-started/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Linode CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.10.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Linode CLI. ](https://www.linode.com/docs/products/tools/cli/get-started/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `LINODE_CLI_TOKEN` | *Thanks to [@alexclst](https://github.com/alexclst) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/86)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to securely authenticate LocalStack The LocalStack shell plugin allows you to use 1Password to securely authenticate [LocalStack ](https://docs.localstack.cloud/getting-started/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate LocalStack with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install LocalStack. ](https://docs.localstack.cloud/getting-started/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | API Key | `LOCALSTACK_API_KEY` | --- ## Use 1Password to securely authenticate MongoDB Atlas The MongoDB Atlas shell plugin allows you to use 1Password to securely authenticate [the Atlas CLI ](https://www.mongodb.com/tools/atlas-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Atlas CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install the Atlas CLI ](https://www.mongodb.com/try/download/atlascli). The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Public key | `MONGODB_ATLAS_PUBLIC_API_KEY` | | Private key | `MONGODB_ATLAS_PRIVATE_API_KEY` | *Thanks to [@joqim](https://github.com/joqim) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/198)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password Shell Plugins to authenticate with multiple accounts # Use shell plugins to authenticate with multiple accounts You can configure [1Password Shell Plugins](/docs/cli/shell-plugins/) to authenticate with different accounts in different directories, so you don't have to spend time signing in or out between projects. For example, you can set the GitHub shell plugin to authenticate with your work credentials in the directories for your work repositories and your personal credentials in the directories for your personal repositories. ## Step 1: Organize your directories by account Before you configure your shell plugins to use multiple accounts, group the project directories on your computer by the accounts they use. For example, if you have a personal and a work GitHub account, you might organize your personal and work GitHub repository folders like this: ``` github/ ├─ personal/ │ ├─ personal-repo-1 │ ├─ personal-repo-2 │ ├─ personal-repo-3 ├─ work/ │ ├─ work-repo-1 │ ├─ work-repo-2 ``` ## Step 2: Configure default credentials for each environment After you organize your projects under account-level directories, you can set default credentials for your shell plugin to use in each directory and all its subfolders. 1. Change directories to one of the account-level folders you created. For example: ```shell cd projects/work ``` 2. Sign in to the 1Password account where the credentials you want to use are stored: ```shell op signin ``` 3. Choose a plugin to initialize, or run `op plugin init` to choose from a list of all available plugins. For example, to initialize the GitHub plugin: ```shell op plugin init gh ``` 4. Import or select the appropriate credentials to use with the account. 5. Select **Use automatically when in this directory or subdirectories** as the default credential scope. 6. Repeat the process in other account-level folders with their respective credentials. This will make the credentials you configure in each account-level folder the default for all subfolders within it, as long as no other directory-specific defaults are set in them. After you set defaults in all your account-level folders, use the shell plugin as you normally would across all your projects. When you use the plugin in a folder within the personal or work directories, the plugin will automatically authenticate with the appropriate credentials. ## Learn more - [Get started with 1Password Shell Plugins](/docs/cli/shell-plugins/) - [Build your own shell plugins](/docs/cli/shell-plugins/contribute/) --- ## Use 1Password to authenticate the MySQL CLI with biometrics # Use 1Password to securely authenticate the MySQL CLI The MySQL shell plugin allows you to use 1Password to securely authenticate [the MySQL CLI ](https://dev.mysql.com/doc/refman/en/mysql.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the MySQL CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the MySQL CLI. ](https://dev.mysql.com/doc/refman/en/installing.html) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference If you saved your MySQL credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If your credentials are stored in a different field, you'll be prompted to select the field manually. Field names are case-insensitive. Field name tokens can be separated by whitespaces, underscores, dashes, or nothing. | 1Password field name | Parameter | | --- | --- | | Host (optional) | `host` | | Port (optional)| `port` | | User (optional) | `user` | | Password | `password` | | Database (optional) | `database` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate ngrok with biometrics # Use 1Password to securely authenticate ngrok The ngrok shell plugin allows you to use 1Password to securely authenticate [the ngrok CLI ](https://ngrok.com/docs/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate ngrok with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.14.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the ngrok CLI ](https://ngrok.com/docs/getting-started). The following shells are supported: - Bash - Zsh - Fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ### Optional: Add an API key The ngrok shell plugin sets up authentication for the following ngrok commands by default: `http`, `service`, `start`, `tcp`, `tls`, and `tunnel`. To configure authentication for the `ngrok api` command, [add a custom field](https://support.1password.com/custom-fields#add-a-custom-field) to your ngrok item titled `API Key` and save [your ngrok API key](https://dashboard.ngrok.com/api/keys) there. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your ngrok credentials in 1Password, you can remove all local copies you previously had stored on disk. To find your ngrok configuration file location, run: ```shell ngrok config check ``` To remove your credentials, run `rm` with the filepath for your configuration file. For example: **Mac:** ```shell rm "~/Library/Application Support/ngrok/ngrok.yml" ``` **Linux:** ```shell rm ~/.config/ngrok/ngrok.yml ``` ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference If you're using ngrok 3.2.1 or later, 1Password authenticates with ngrok by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you're using an earlier version of ngrok, 1Password authenticates by injecting a temporary file with the appropriate credentials. If you saved your ngrok credentials in 1Password manually rather than using `op plugin init` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | YAML config field | Environment variable | | --- | --- | --- | | Auth Token | `authtoken` | `NGROK_AUTHTOKEN` | | API Key | `api_key` | `NGROK_API_KEY` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/165)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password Shell Plugins with NixOS or home-manager # Configure shell plugins using Nix If you're using Nix to manage your shell configuration, you can configure 1Password Shell Plugins natively within your Nix configuration. 1. Add the 1Password Shell Plugins flake to your flake inputs: ```nix [{ "color": "bitsblue", "lineNo": 6, "substr": "_1password-shell-plugins.url = \\"github:1Password/shell-plugins\\";"}] { description = "My NixOS system flake"; inputs = { nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; # import the 1Password Shell Plugins Flake _1password-shell-plugins.url = "github:1Password/shell-plugins"; # the rest of your flake inputs here }; outputs = inputs@{ nixpkgs, ... }: { # the rest of your flake here } } ``` 2. Somewhere in your flake output configuration, import and use the appropriate module: **NixOS without home-manager:** ```nix [{"color": "bitsblue", "lineNo": 3, "substr": "inputs._1password-shell-plugins.nixosModules.default"}] { # import the NixOS module imports = [ inputs._1password-shell-plugins.nixosModules.default ]; programs._1password-shell-plugins = { # enable 1Password shell plugins for bash, zsh, and fish shell enable = true; # the specified packages as well as 1Password CLI will be # automatically installed and configured to use shell plugins plugins = with pkgs; [ gh awscli2 cachix ]; }; # this can also be `programs.bash` or `programs.fish` programs.zsh = { enable = true; # the rest of your shell configuration here }; } ``` **Nix with home-manager:** ```nix [{"color": "bitsblue", "lineNo": 3, "substr": "inputs._1password-shell-plugins.hmModules.default"}] { # import the home-manager module imports = [ inputs._1password-shell-plugins.hmModules.default ]; programs._1password-shell-plugins = { # enable 1Password shell plugins for bash, zsh, and fish shell enable = true; # the specified packages as well as 1Password CLI will be # automatically installed and configured to use shell plugins plugins = with pkgs; [ gh awscli2 cachix ]; }; # this can also be `programs.bash` or `programs.fish` programs.zsh = { enable = true; # the rest of your shell configuration here }; } ``` 3. Apply the updated configuration: **NixOS (including home-manager as a NixOS module):** ~/path/to/flake/directory/ should be the path to the directory containing your `flake.nix` file, and my-computer should be the name of the flake output to use as the system configuration. ```shell [{"color": "bitsblue", "lineNo": 1, "substr": "~/path/to/flake/directory/"}, {"color": "green", "lineNo": 1, "substr": "my-computer"}] sudo nixos-rebuild switch --flake "~/path/to/flake/directory/.#my-computer" ``` **Nix with standalone home-manager:** ~/path/to/flake/directory/ should be the path to the directory containing your `flake.nix` file, and my-computer should be the name of the flake output to use as the system configuration. ```shell [{"color": "bitsblue", "lineNo": 1, "substr": "~/path/to/flake/directory/"}, {"color": "green", "lineNo": 1, "substr": "my-computer"}] home-manager switch --flake "~/path/to/flake/directory/.#my-computer" ``` --- ## Use 1Password to securely authenticate Oh Dear CLI The Oh Dear CLI shell plugin allows you to use 1Password to securely authenticate [Oh Dear CLI ](https://github.com/ohdearapp/ohdear-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Oh Dear CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.19.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install Oh Dear CLI ](https://github.com/ohdearapp/ohdear-cli). The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `OHDEAR_API_TOKEN` | *Thanks to [@owenvoke](https://github.com/owenvoke) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/269)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Okta CLI with biometrics # Use 1Password to securely authenticate the Okta CLI The Okta shell plugin allows you to use 1Password to securely authenticate [the Okta CLI ](https://cli.okta.com/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Okta CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Okta CLI. ](https://cli.okta.com/manual#installation) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | --- | --- | | Token | `OKTA_CLIENT_TOKEN` | | Org URL | `OKTA_CLIENT_ORGURL` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to securely authenticate OpenAI Evals The OpenAI Evals shell plugins allow you to use 1Password to securely authenticate [`oaieval` and `oaievalset` ](https://github.com/openai/evals/blob/main/docs/run-evals.md) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials for each CLI and source the `plugins.sh` file, then you'll be prompted to authenticate OpenAI Evals with biometrics. :::tip You can also use 1Password Shell Plugins to authenticate [OpenAI](/docs/cli/shell-plugins/openai). ::: ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.19.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install OpenAI Evals. ](https://github.com/openai/evals/blob/main/docs/run-evals.md) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your oaieval credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Configure your oaievalset credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 3: Source the plugins.sh file **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 4: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 5: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | API Key | `OPENAI_API_KEY` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/208)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the OpenAI CLI with biometrics # Use 1Password to securely authenticate the OpenAI CLI The OpenAI shell plugin allows you to use 1Password to securely authenticate [the OpenAI CLI ](https://pypi.org/project/openai/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the OpenAI CLI with biometrics. :::tip You can also use 1Password Shell Plugins to authenticate [OpenAI Evals](/docs/cli/shell-plugins/openai-evals). ::: ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.13.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the OpenAI CLI. ](https://pypi.org/project/openai/) The following shells are supported: - Bash - Zsh - fish ## Before you begin: Create and save an OpenAI API key If you've already created an OpenAI API key, [skip to step 1](#step-1-configure-your-default-credentials). If you haven't created an API key yet, you can create one and use the [1Password browser extension](https://support.1password.com/getting-started-browser/) to quickly save it in 1Password: 1. Open and unlock [1Password in your browser](https://support.1password.com/getting-started-browser/). 2. [Follow the steps](https://platform.openai.com/account/api-keys) to create an OpenAI API key. 3. Select **Save item** when 1Password asks if you want to save an item for the OpenAI API key. 4. Choose the vault where you want to save the item, edit the item's name and details, then select **Save item**. _[The prompt to save your OpenAI API key in 1Password.]_ ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | API Key | `OPENAI_API_KEY` | *Thanks to [@jodyheavener](https://github.com/jodyheavener) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/152)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to securely authenticate Pipedream CLI The Pipedream CLI shell plugin allows you to use 1Password to securely authenticate [Pipedream CLI ](https://pipedream.com/docs/cli/install/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Pipedream CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Pipedream CLI. ](https://pipedream.com/docs/cli/install/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with Pipedream by injecting a temporary config file with the credentials required by the plugin commands directly from your 1Password account. If you saved your Pipedream credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Config file field | | --- | --- | | API Key | api_key | | Org ID | org_id | *Thanks to [@rajapri28613](https://github.com/rajapri28613) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/338)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to authenticate psql with biometrics # Use 1Password to securely authenticate the PostgreSQL CLI The PostgreSQL shell plugin allows you to use 1Password to securely authenticate [psql ](https://www.postgresguide.com/utilities/psql/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate psql with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [psql. ](https://www.postgresql.org/docs/current/app-psql.html) The following shells are supported: - Bash - Zsh - fish ## Additional executables You can also use the PostgreSQL shell plugin with: - [`pg_dump` ](https://www.postgresql.org/docs/current/app-pgdump.html) - [`pg_restore` ](https://www.postgresql.org/docs/current/app-pgrestore.html) - [`pgcli` ](https://www.pgcli.com/) Run `op plugin init ` with the executable you want to configure, then follow the steps to select your credentials. ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | --- | --- | | Server | `PGHOST` | | Port (optional) | `PGPORT` | | Username | `PGUSER` | | Password (optional) | `PGPASSWORD` | | Database (optional) | `PGDATABASE` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Pulumi CLI with biometrics # Use 1Password to securely authenticate the Pulumi CLI The Pulumi CLI shell plugin allows you to use 1Password to securely authenticate [the Pulumi CLI ](https://www.pulumi.com/docs/reference/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Pulumi CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Pulumi CLI. ](https://www.pulumi.com/docs/get-started/install/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `PULUMI_ACCESS_TOKEN` | | Host (optional) | `PULUMI_BACKEND_URL` | *Thanks to [@ringods](https://github.com/ringods) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/199)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the ReadMe CLI with biometrics # Use 1Password to securely authenticate the ReadMe CLI The ReadMe shell plugin allows you to use 1Password to securely authenticate [the ReadMe CLI ](https://docs.readme.com/main/docs/rdme) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the ReadMe CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.12.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the ReadMe CLI. ](https://github.com/readmeio/rdme#setup) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | --- | --- | | API Key | `RDME_API_KEY` | | Username (Optional) | `RDME_EMAIL` | | Website (Optional) | `RDME_PROJECT` | *Thanks to [@kanadgupta](https://github.com/kanadgupta) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/106)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## About 1Password Shell Plugins security ## Authorization model To get your consent when a 1Password CLI command or 1Password Shell Plugin is invoked, 1Password will present you with an approval dialog: _[A CLI being authenticated using 1Password CLI biometric unlock.]_ This dialog will show which application is requesting permission to use which 1Password account. After you approve the request, a *session* will be established between 1Password and the terminal window or tab the plugin was invoked from. Any consecutive invocations of 1Password CLI within that terminal window can use your 1Password account without additional authorization until 1Password locks. This includes invocations of the same plugin, a different plugin and any other 1Password CLI commands. As always when working with secrets, it's worth being mindful of the processes, scripts, and plugins you run that can access those secrets. A session is ended in any of the following scenarios: - When 1Password is locked - After 10 minutes of inactivity - After 12 hours - When `op signout` is run in the authorized terminal session - When `op signout --all` is run in any terminal session ## Extendability & community contributions 1Password Shell Plugins is [extendable](/docs/cli/shell-plugins/contribute/). Contributed plugins are curated and reviewed by 1Password before they are included and shipped in 1Password CLI. 1Password has only reviewed contributed plugins if they are included in 1Password CLI. We recommend you only run plugins included in 1Password CLI and plugins you've written yourself. In practice, this means you should not download binaries and place them in `~/.op/plugins/local`. ## Learn more - [Biometric security](/docs/cli/app-integration/) --- ## Use 1Password to authenticate the Sentry CLI with biometrics # Use 1Password to securely authenticate the Sentry CLI The Sentry shell plugin allows you to use 1Password to securely authenticate [the Sentry CLI ](https://docs.sentry.io/product/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Sentry CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Sentry CLI. ](https://docs.sentry.io/product/cli/installation/) The following shells are supported: - Bash - Zsh - fish :::tip Get $240 in Sentry credits when you [create a new Sentry account](https://sentry.io/signup/) using the promo code **1Password**. ::: ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables| | --- | --- | | Token | `SENTRY_AUTH_TOKEN` | | Organization (optional) | `SENTRY_ORG` | | Project (optional) | `SENTRY_PROJECT` | | URL (optional) | `SENTRY_URL` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate SnowSQL with biometrics # Use 1Password to securely authenticate the Snowflake CLI The Snowflake shell plugin allows you to use 1Password to securely authenticate [SnowSQL ](https://docs.snowflake.com/en/user-guide/snowsql.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the SnowSQL with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.14.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [SnowSQL. ](https://docs.snowflake.com/en/user-guide/snowsql-install-config) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | --- | --- | | Account | `SNOWSQL_ACCOUNT` | | Username | `SNOWSQL_USER`| | Password | `SNOWSQL_PWD` | *Thanks to [@williamhpark](https://github.com/williamhpark) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/161)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Snyk CLI with biometrics # Use 1Password to securely authenticate the Snyk CLI The Snyk shell plugin allows you to use 1Password to securely authenticate [the Snyk CLI ](https://docs.snyk.io/snyk-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Snyk CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Snyk CLI. ](https://docs.snyk.io/snyk-cli/install-the-snyk-cli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `SNYK_TOKEN` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Sourcegraph CLI with biometrics # Use 1Password to securely authenticate the Sourcegraph CLI The Sourcegraph shell plugin allows you to use 1Password to securely authenticate [the Sourcegraph CLI ](https://docs.sourcegraph.com/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Sourcegraph CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.14.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Sourcegraph CLI. ](https://docs.sourcegraph.com/cli/quickstart) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | --- | --- | | Endpoint | `SRC_ENDPOINT` | | Token | `SRC_ACCESS_TOKEN`| *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/146)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Stripe CLI with biometrics # Use 1Password to securely authenticate the Stripe CLI The Stripe shell plugin allows you to use 1Password to securely authenticate [the Stripe CLI ](https://stripe.com/docs/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Stripe CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Stripe CLI. ](https://stripe.com/docs/stripe-cli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | API Key | `STRIPE_API_KEY` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to securely authenticate Terraform # Use 1Password to securely authenticate Terraform (Beta) The Terraform shell plugin allows you to use 1Password to securely authenticate [Terraform CLI ](https://developer.hashicorp.com/terraform/cli) to supported providers with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. You can configure the Terraform plugin to authenticate with biometrics to any provider in the [1Password Shell Plugin ecosystem](/docs/cli/shell-plugins#get-started), like AWS, ngrok, and Databricks. :::tip The Terraform shell plugin is currently in beta. It can only be used with the latest [beta build](/docs/cli/reference#beta-builds) of 1Password CLI. ::: ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [the latest beta build of 1Password CLI](/docs/cli/reference#beta-builds) (`2.19.0-beta.01` or later). 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/app-integration#step-1-turn-on-the-app-integration). 5. Install [Terraform CLI ](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli). The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials :::tip If you have multiple 1Password accounts, run `op signin` to select the account you want to use before configuring the plugin. When you use the plugin, 1Password CLI will automatically switch to that account. ::: To get started with the Terraform shell plugin, run: ```shell op plugin init terraform ``` You'll be prompted to select the credential types you want to use with Terraform — you can choose as many as you want. Select the credential type for [a supported provider](/docs/cli/shell-plugins#get-started), then you can either [import the credential](#import-a-new-item) into your 1Password account or [select an existing 1Password item](#select-an-existing-item) where the credential is saved. When you've configured all the credentials you want to use with Terraform, select **Stop choosing credentials**. Step 1.1: Import or select an item #### Import a new item If you haven't saved a credential in 1Password yet, select **Import into 1Password**. Enter a name for the new 1Password item and select the vault where you want to save it. If 1Password detects the credential in your local development environment, you'll be prompted to import it automatically. #### Select an existing item If you've already saved a credential in 1Password, select **Search in 1Password**. Select the item from the list of suggested items. If you don't see the item you want, select **Expand search** to browse all items in your account. Step 1.2: Set default credential scope After you finish selecting your credentials, you'll be prompted to configure when to use them. - **Prompt me for each new terminal session** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the defaults will be removed. - **Use automatically when in this directory or subdirectories** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. - **Use as global default on my system** will set the credentials as the defaults in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you use Terraform CLI with one of the providers you configured credentials for, you'll be prompted to authenticate with biometrics or system authentication. _[The terraform plan command being authenticated to AWS with Touch ID.]_ ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk, like in your [provider configurations ](https://developer.hashicorp.com/terraform/language/providers/configuration). ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current Terraform configuration: ```shell op plugin inspect terraform ``` 1Password CLI will return a list of the credentials you've configured to use with Terraform and their default scope, as well as a list of aliases configured for Terraform CLI. _[1Password CLI inspecting a Terraform shell plugin with AWS and ngrok credentials configured as global defaults.]_ Clear your credentials To reset the credentials used with Terraform CLI: ```shell op plugin clear terraform ``` You can clear one configuration at a time, in this order of precedence: 1. Terminal session default 2. Directory default, from the current directory to `$HOME` 3. Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear terraform` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear terraform --all`. ## Reference 1Password authenticates to Terraform providers by provisioning the credentials required by the plugin commands directly from your 1Password account. If you saved your provider credentials manually rather than using `op plugin` to import a new item, you might be prompted to rename your item's fields to match the item structure required by the credential schema. --- ## Test shell plugins You can test [1Password Shell Plugins](/docs/cli/shell-plugins/) without making any changes to your current workflows. To do this, you'll configure a shell plugin with default credentials that only last for the duration of your current terminal session, then source the shell plugin aliases script in your current terminal session instead of adding it to your shell profile. When you close your terminal window, your temporary shell plugin configuration will be cleared. ## Step 1: Temporarily configure a shell plugin 1. Sign in to the 1Password account where the credentials you want to use with the shell plugin are stored: ```shell op signin ``` 2. Choose a plugin to test, or run `op plugin init` to choose from a list of all available plugins. For example, to test the AWS shell plugin: ```shell op plugin init aws ``` 3. Import or select the credentials you want to test with the plugin. 4. When you're prompted to choose when the credentials will be used to authenticate, select **Prompt me for each new terminal session**. This will configure your credentials as a temporary default for the duration of your current terminal session. 5. Instead of adding the command to source the `plugins.sh` file to your shell profile, source the `plugins.sh` file in your current terminal session. This will create an alias for the CLI executable that lasts for the duration of your current terminal session. For example: ```shell source ~/.config/op/plugins.sh ``` The location of the `plugins.sh` file will vary depending on your [configuration directory](/docs/cli/config-directories/). ## Step 2: Test the shell plugin You can test the shell plugin for the duration of your current terminal session. 1. Sign out of 1Password CLI to make sure you'll be prompted to authenticate: ```shell op signout ``` 2. Run a command with the CLI that requires authentication. For example, if you configured a shell plugin for AWS: ```shell aws s3 ls ``` When you're done testing, close the terminal window to clear your default credentials and remove the alias for the CLI executable. To continue using a shell plugin, follow the installation guide for the [plugin of your choice](/docs/cli/shell-plugins/). --- ## Use 1Password to securely authenticate Todoist CLI The Todoist CLI shell plugin allows you to use 1Password to securely authenticate [Todoist CLI ](https://github.com/sachaos/todoist) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Todoist CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Todoist CLI. ](https://github.com/sachaos/todoist) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with Todoist by injecting a temporary config file with the credentials required by the plugin commands directly from your 1Password account. If you saved your Todoist credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Config file field | | --- | --- | | Token | token | *Thanks to [@rajapri28613](https://github.com/rajapri28613) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/340)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to authenticate the Treasure Data CLI with biometrics # Use 1Password to securely authenticate the Treasure Data CLI The Treasure Data shell plugin allows you to use 1Password to securely authenticate the [Treasure Data Toolbelt ](https://www.treasuredata.com/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Treasure Data with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.16.1 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Treasure Data Toolbelt ](https://toolbelt.treasuredata.com/). The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | API Key | `TD_API_KEY` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## 1Password Shell Plugins troubleshooting ## Using shell plugins ### If you're using a non-interactive shell 1Password Shell Plugins are built to be used with interactive shells. An interactive shell is required for the shell plugin to prompt for authentication. ### If your script doesn't inherit shell plugin aliases Scripts might not inherit your shell plugin aliases if they're run in a subshell where the `plugins.sh` file isn't sourced. When this happens, the CLI command in the script will output an error instead of running correctly. For example, the following script runs a `doctl` command in a subshell, and as a result wouldn't inherit the `doctl` shell plugin alias: ```html title="yourscript.sh" #!/usr/bin/env bash doctl account get ``` To make the script run correctly, you can wrap the `doctl` command in [`op plugin run`](/docs/cli/reference/management-commands/plugin#plugin-run). For example: ```html title="yourscript.sh" #!/usr/bin/env bash op plugin run doctl account get ``` ### If autocompletion stops working If autocompletion stops working in Zsh after you configure a shell plugin, run the following command to configure completion for aliases: ```shell setopt completealiases ``` ## Contributing shell plugins ### If your locally-built plugin stops working If your locally-built plugin stops working, you might need to update your 1Password CLI version or rebuild your plugin with the latest shell plugins SDK. #### Update your 1Password CLI installation If you're using an outdated version of the CLI, you'll see this error message: ```shell 1Password CLI is outdated, please run: op update to update 1Password CLI to the latest version and to be able to use this Shell Plugin. ``` To update your 1Password CLI installation to the latest version: ```shell op update ``` Or [update 1Password CLI with a package manager](/docs/cli/reference/update#update-with-a-package-manager). #### Rebuild your plugins with the latest shell plugins SDK If the shell plugins SDK is outdated, you'll see this error message: ```shell 1Password Shell Plugin is out of date. Remove the plugin at '/Users//.op/plugins/local/aws' or rebuild it with the latest Shell Plugin SDK to use it. ``` To update to the latest shell plugins SDK, you'll need to merge the `main` branch of the [shell plugins repository](https://github.com/1Password/shell-plugins/tree/main/) into the branch for your plugin. To do this: 1. Navigate to the directory where you cloned the shell plugins repo: ```shell cd ``` 2. If you've made any local changes to your plugin branch, commit or stash them: ```shell git commit -am "" ``` 3. Check out the `main` branch: ```shell git checkout main ``` 4. Pull the `main` branch: ```shell git pull main ``` 5. Check out your plugin branch: ```shell git checkout ``` 6. Merge `main` into your branch: ``` git merge main ``` Then fix any merge conflicts and make any needed changes to the plugin code to conform to the latest version of the SDK. When you're ready to rebuild your plugin: ```shell make /build ``` :::info Join our Developer Slack If you're still having trouble, join our [Developer Slack workspace](https://developer.1password.com/joinslack) and we'll help you figure out a solution. ::: ## Learn more - [Uninstall shell plugins](/docs/cli/shell-plugins/uninstall/) - [Test shell plugins](/docs/cli/shell-plugins/test/) - [Use shell plugins to switch between multiple environments](/docs/cli/shell-plugins/environments/) - [Use shell plugins with multiple accounts](/docs/cli/shell-plugins/multiple-accounts/) --- ## Use 1Password to authenticate the Tugboat CLI with biometrics # Use 1Password to securely authenticate the Tugboat CLI The Tugboat shell plugin allows you to use 1Password to securely authenticate [the Tugboat CLI ](https://docs.tugboatqa.com/tugboat-cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Tugboat CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.10.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Tugboat CLI. ](https://docs.tugboatqa.com/tugboat-cli/install-the-cli/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Token | `TUGBOAT_API_TOKEN` | *Thanks to [@markdorison](https://github.com/markdorison) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/85)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to authenticate the Twilio CLI with biometrics # Use 1Password to securely authenticate the Twilio CLI The Twilio shell plugin allows you to use 1Password to securely authenticate [the Twilio CLI ](https://twilio.com/docs/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Twilio CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Twilio CLI. ](https://www.twilio.com/docs/twilio-cli/quickstart) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | --- | --- | | Account SID | `TWILIO_ACCOUNT_SID` | | API Key | `TWILIO_API_KEY` | | API Secret | `TWILIO_API_SECRET` | | Region (optional) | `TWILIO_REGION` | Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Uninstall shell plugins [1Password Shell Plugins](/docs/cli/shell-plugins/) are built so you can stop using them at any time. - If you want to [reset a shell plugin configuration](#clear-your-default-credentials-for-a-plugin), you can clear your default credentials. - If you want to [temporarily stop using a shell plugin](#temporarily-stop-using-a-shell-plugin), you can run `unalias ` or remove the alias for its executable from your `plugins.sh` file. - If you want to [temporarily stop using all shell plugins](#temporarily-stop-using-all-shell-plugins), you can remove the command to source the `plugins.sh` file from your shell profile. - And if you want to [completely uninstall shell plugins](#completely-stop-using-shell-plugins), you can do that too. ## Clear your default credentials for a plugin If you want to remove your default credentials for a shell plugin: ```shell op plugin clear ``` Credentials will be removed in this order: 1. Terminal session default 2. Directory default, from the current directory to `$HOME` 3. Global default To remove all the credentials you've configured for a shell plugin at the same time: ```shell op plugin clear --all ``` ## Temporarily stop using a shell plugin If you want to stop using a shell plugin for the current terminal session, run: ``` unalias ``` If you want to temporarily stop using a plugin for a longer period of time, you can remove its alias from your `plugins.sh` file. Then 1Password CLI will no longer handle authentication when you use the third-party CLI. 1. Open your [`plugins.sh` file](#if-you-cant-find-your-pluginssh-file) file. 2. Remove the alias for the plugin you want to stop using. For example, `alias aws="op plugin run -- aws"`. 3. Save the file. 4. Open a new terminal window or source your shell profile for the change to go into effect. You can add the alias back to the file at any time to continue using the shell plugin with your current setup. ## Temporarily stop using all shell plugins If you want to temporarily stop using shell plugins without losing your configurations, you can remove the command to source the `plugins.sh` file from your shell profile. 1. Open your shell profile. 2. Remove the line that looks like this. Your [`plugins.sh` file path](#if-you-cant-find-your-pluginssh-file) may vary. ```shell source ~/.config/op/plugins.sh ``` 3. Open a new terminal session or source your shell profile for the change to go into effect. 1Password will no longer prompt you to authenticate for any third-party CLI. ## Completely stop using shell plugins To completely stop using shell plugins and remove all information about your configurations: 1. [Clear the default credentials](#clear-your-default-credentials-for-a-plugin) for each of your plugins. 2. [Remove the command to source the `plugins.sh` file](#temporarily-stop-using-all-shell-plugins) from your shell profile. 3. Delete the [`plugins.sh` file](#if-you-cant-find-your-pluginssh-file) and the `plugins` folder within your `op` directory. 4. If you configured any directory-specific defaults, remove the `.op` folder from those directories. ## Get help ### If you can't find your plugins.sh file The file path for your `plugins.sh` file may vary depending on your [configuration directory](/docs/cli/config-directories/). Common locations include: - `~/.op/plugins.sh` - `~/.config/op/plugins.sh` - `~/op/plugins.sh` --- ## Use 1Password to securely authenticate Upstash CLI The Upstash CLI shell plugin allows you to use 1Password to securely authenticate [Upstash CLI ](https://github.com/upstash/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Upstash CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Upstash CLI. ](https://github.com/upstash/cli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | API Key | `UPSTASH_API_KEY` | | Email | `UPSTASH_EMAIL` | *Thanks to [@siddhikhapare](https://github.com/siddhikhapare) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/316)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to securely authenticate Vercel CLI The Vercel CLI shell plugin allows you to use 1Password to securely authenticate [Vercel CLI ](https://vercel.com/docs/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Vercel CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.19.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install Vercel CLI ](https://vercel.com/docs/cli). The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with Vercel by injecting injecting the token as a command line argument. If you saved your Vercel CLI credentials in 1Password manually rather than using `op plugin init` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Command line argument | | --- | --- | | Token | `--token` | ` *Thanks to [@j178](https://github.com/j178) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/273)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to securely authenticate Vertica CLI The Vertica CLI shell plugin allows you to use 1Password to securely authenticate [Vertica CLI ](https://www.vertica.com/docs/9.2.x/HTML/Content/Authoring/ConnectingToVertica/vsql/Install/InstallingTheVsqlClient.htm) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Vertica CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Vertica CLI. ](https://www.vertica.com/docs/9.2.x/HTML/Content/Authoring/ConnectingToVertica/vsql/Install/InstallingTheVsqlClient.htm) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Username | `VSQL_USER` | | Password | `VSQL_PASSWORD` | | Host (optional) | `VSQL_HOST` | | Port (optional) | `VSQL_PORT` | | Database | `VSQL_DATABASE` | *Thanks to [@parthiv11](https://github.com/parthiv11) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/327)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to authenticate Vultr CLI with biometrics # Use 1Password to securely authenticate Vultr CLI The Vultr CLI shell plugin allows you to use 1Password to securely authenticate [Vultr CLI ](https://github.com/vultr/vultr-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Vultr CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.14.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Vultr CLI. ](https://github.com/vultr/vultr-cli#installation) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | --- | --- | | API Key | `VULTR_API_KEY` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/159)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## Use 1Password to securely authenticate YugabyteDB SQL Shell The YugabyteDB SQL Shell shell plugin allows you to use 1Password to securely authenticate [YugabyteDB SQL Shell ](https://docs.yugabyte.com/preview/admin/ysqlsh/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate YugabyteDB SQL Shell with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install YugabyteDB SQL Shell. ](https://docs.yugabyte.com/preview/admin/ysqlsh/) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Host | `PGHOST` | | Port | `PGPORT` | | Username | `PGUSER` | | Password | `PGPASSWORD` | *Thanks to [@parthiv11](https://github.com/parthiv11) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/322)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to securely authenticate Zapier CLI The Zapier CLI shell plugin allows you to use 1Password to securely authenticate [Zapier CLI ](https://platform.zapier.com/cli_docs/docs) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Zapier CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password 8 for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Connect 1Password CLI with the 1Password app](/docs/cli/app-integration/). 5. [Install Zapier CLI. ](https://platform.zapier.com/cli_docs/docs) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **Fish:** ```shell echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Key | `ZAPIER_DEPLOY_KEY` | *Thanks to [@rajapri28613](https://github.com/rajapri28613) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/337)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute).* --- ## Use 1Password to authenticate the Zendesk CLI with biometrics # Use 1Password to securely authenticate the Zendesk CLI The Zendesk CLI shell plugin allows you to use 1Password to securely authenticate [ZCLI ](https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate ZCLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later. If you've already installed 1Password CLI, learn how to update your installation. 4. [Integrate 1Password CLI with the 1Password app](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [ZCLI. ](https://developer.zendesk.com/documentation/apps/getting-started/using-zcli#installing-and-updating-zcli) The following shells are supported: - Bash - Zsh - fish ## Step 1: Configure your default credentials To get started with the shell plugin: Sign in to the 1Password account you want to use with the plugin: ```shell op signin ``` If you only want to configure the plugin in a specific directory, change to that directory Run the command to set up the plugin:```shell op plugin init $ ``` You'll be prompted to import your credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. Step 1.1: Import or select an item Import a new item If you haven't saved your credentials in 1Password yet, select Import into 1Password. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be prompted to import them automatically. Select an existing item If you've already saved your credentials in 1Password, select Search in 1Password. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select Expand search to browse all items in your account. Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate . "Prompt me for each new terminal session" will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed. "Use automatically when in this directory or subdirectories" will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. "Use as global default on my system" will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your configuration directory. `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: **Bash:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` **Zsh:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` **fish:** ```shell echo "source ~/.config/op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with , you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support more than 60 third-party CLIs. To see a list of supported CLIs: ```shell op plugin list ``` To choose another plugin to get started with: ```shell op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in multiple environments or with multiple accounts. ## Get help Inspect your configuration To inspect your current configuration: ```shell op plugin inspect $ ``` 1Password CLI will return a list of the credentials you've configured to use with and their default scopes, as well as a list of aliases configured for . Clear your credentials To reset the credentials used with : ```shell op plugin clear $ ``` You can clear one configuration at a time, in this order of precedence: Terminal session default Directory default, from the current directory to `$HOME` Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | --- | --- | | Subdomain | `ZENDESK_SUBDOMAIN` | | Email | `ZENDESK_EMAIL` | | Token | `ZENDESK_API_TOKEN` | *Thanks to [@williamhpark](https://github.com/williamhpark) for [contributing this plugin](https://github.com/1Password/shell-plugins/pull/207)! Learn how to [build your own shell plugins](/docs/cli/shell-plugins/contribute/).* Learn more Use shell plugins to switch between multiple environments Use shell plugins with multiple accounts Build your own shell plugins --- ## 1Password Shell Plugins # Use 1Password Shell Plugins to securely authenticate any CLI With 1Password Shell Plugins, you can configure 1Password to securely authenticate third-party CLIs with your fingerprint, Apple Watch, or system authentication. Your CLI credentials are stored in your 1Password account, so you never have to manually enter your credentials or store them in plaintext. You can [test shell plugins](/docs/cli/shell-plugins/test/) or choose a shell plugin from the [list below](#get-started) to get started. Shell plugins are compatible with the following shells: - Bash - Zsh - fish ## Get started [_[]_ Akamai](/docs/cli/shell-plugins/akamai/) [_[]_ Argo CD](/docs/cli/shell-plugins/argo-cd/) [_[]_ Axiom](/docs/cli/shell-plugins/axiom) [_[]_ AWS](/docs/cli/shell-plugins/aws/) [_[]_ AWS CDK Toolkit](/docs/cli/shell-plugins/aws-cdk-toolkit/) [_[]_ Binance](/docs/cli/shell-plugins/binance) [_[]_ Cachix](/docs/cli/shell-plugins/cachix/) [_[]_ Cargo](/docs/cli/shell-plugins/cargo/) [_[]_ CircleCI](/docs/cli/shell-plugins/circleci/) [_[]_ Civo](/docs/cli/shell-plugins/civo) [_[]_ Cloudflare Workers](/docs/cli/shell-plugins/cloudflare-workers/) [_[]_ Crowdin](/docs/cli/shell-plugins/crowdin) [_[]_ Databricks](/docs/cli/shell-plugins/databricks/) [_[]_ DigitalOcean](/docs/cli/shell-plugins/digitalocean/) [_[]_ Dogshell](/docs/cli/shell-plugins/datadog/) [_[]_ Fastly](/docs/cli/shell-plugins/fastly/) [_[]_ Flyctl](/docs/cli/shell-plugins/flyctl) [_[]_ FOSSA](/docs/cli/shell-plugins/fossa/) [_[]_ Gitea](/docs/cli/shell-plugins/gitea/) [_[]_ GitHub](/docs/cli/shell-plugins/github/) [_[]_ GitLab](/docs/cli/shell-plugins/gitlab/) [_[]_ HashiCorp Vault](/docs/cli/shell-plugins/hashicorp-vault/) [_[]_ Heroku](/docs/cli/shell-plugins/heroku/) [_[]_ Hetzner Cloud](/docs/cli/shell-plugins/hetzner-cloud/) [_[]_ Homebrew](/docs/cli/shell-plugins/homebrew/) [_[]_ HuggingFace](/docs/cli/shell-plugins/huggingface) [_[]_ InfluxDB](/docs/cli/shell-plugins/influxdb) [_[]_ Kaggle](/docs/cli/shell-plugins/kaggle) [_[]_ Lacework](/docs/cli/shell-plugins/lacework/) [_[]_ Laravel Forge](/docs/cli/shell-plugins/laravel-forge/) [_[]_ Laravel Vapor](/docs/cli/shell-plugins/laravel-vapor/) [_[]_ Linode](/docs/cli/shell-plugins/linode/) [_[]_ LocalStack](/docs/cli/shell-plugins/localstack/) [_[]_ MongoDB Atlas](/docs/cli/shell-plugins/mongodb-atlas) [_[]_ MySQL](/docs/cli/shell-plugins/mysql/) [_[]_ ngrok](/docs/cli/shell-plugins/ngrok/) [_[]_ Oh Dear](/docs/cli/shell-plugins/oh-dear/) [_[]_ Okta](/docs/cli/shell-plugins/okta/) [_[]_ OpenAI](/docs/cli/shell-plugins/openai/) [_[]_ OpenAI Evals](/docs/cli/shell-plugins/openai-evals/) [_[]_ Pipedream](/docs/cli/shell-plugins/pipedream) [_[]_ PostgreSQL](/docs/cli/shell-plugins/postgresql/) [_[]_ Pulumi](/docs/cli/shell-plugins/pulumi/) [_[]_ ReadMe](/docs/cli/shell-plugins/readme/) [_[]_ Sentry](/docs/cli/shell-plugins/sentry/) [_[]_ Snowflake](/docs/cli/shell-plugins/snowflake/) [_[]_ Snyk](/docs/cli/shell-plugins/snyk/) [_[]_ Sourcegraph](/docs/cli/shell-plugins/sourcegraph/) [_[]_ Stripe](/docs/cli/shell-plugins/stripe/) [_[]_ Terraform](/docs/cli/shell-plugins/terraform/) [_[]_ Todoist](/docs/cli/shell-plugins/todoist) [_[]_ Treasure Data](/docs/cli/shell-plugins/treasure-data/) [_[]_ Tugboat](/docs/cli/shell-plugins/tugboat/) [_[]_ Twilio](/docs/cli/shell-plugins/twilio/) [_[]_ Upstash](/docs/cli/shell-plugins/upstash) [_[]_ Vercel](/docs/cli/shell-plugins/vercel/) [_[]_ Vertica](/docs/cli/shell-plugins/vertica) [_[]_ Vultr](/docs/cli/shell-plugins/vultr/) [_[]_ YugabyteDB](/docs/cli/shell-plugins/yugabytedb/) [_[]_ Zapier](/docs/cli/shell-plugins/zapier) [_[]_ Zendesk](/docs/cli/shell-plugins/zendesk/) ## Your favorite tool not listed? Find out how to [build your own plugin](/docs/cli/shell-plugins/contribute/). --- ## Sign in to your 1Password account manually If you don't want to [use the 1Password app to sign in to 1Password CLI](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration), you can manually add and sign in to your accounts in the terminal. :::danger Known security risks If you sign in to 1Password CLI manually, any process running under the current user can, on some platforms, potentially access your 1Password account. We recommend you [use the 1Password app to sign in to 1Password CLI](/docs/cli/app-integration/) because it offers more robust security guarantees. ::: When you sign in manually in the terminal, 1Password CLI stores your session key encrypted on disk and the random wrapper key used in the environment of the current shell. Sessions expire after 30 minutes of inactivity, after which you’ll need to sign in again and save a new token. If you want to immediately terminate your authenticated session, you can run `op signout`. ## Sign in manually ### Step 1: Add an account To manually add a 1Password account to 1Password CLI, use [`op account add`](/docs/cli/reference/management-commands/account/): ```shell op account add ``` 1Password CLI will prompt you to enter your [sign-in address](https://support.1password.com/sign-in-troubleshooting#if-youre-asked-for-a-sign-in-address), email address, [Secret Key](https://support.1password.com/secret-key/), and 1Password account password. :::tip For non-interactive shells in local environments, sign in with the [1Password desktop app integration](/docs/cli/app-integration/) instead. For non-interactive shells in remote environments, authenticate with a [service account](/docs/service-accounts/) or a [Connect server](/docs/connect/). ::: #### Set a custom account shorthand 1Password CLI uses account shorthands to refer to each of the accounts you add. The default shorthand is your [sign-in address](https://support.1password.com/sign-in-troubleshooting#if-youre-asked-for-a-sign-in-address) subdomain (for example, `my` for `my.1password.com`). To set a custom shorthand, include the `--shorthand` flag when you add an account. For example, to add an account with the shorthand `personal`: ```shell op account add --shorthand personal ``` ### Step 2: Sign in If you added your accounts to 1Password CLI manually, you'll need to use the [manual sign-in command](/docs/cli/reference/commands/signin/) to sign in. This command also works with the [app integration](/docs/cli/app-integration) turned on, so you can use it in scripts to provide compatibility for all users regardless of their sign-in method. **Bash, Zsh, sh, fish:** ```shell eval "$(op signin)" ``` **PowerShell:** ```powershell Invoke-Expression "$(op signin)" ``` After you sign in, 1Password CLI creates a session token and sets the `OP_SESSION` environment variable to it. Include the `--raw` flag to get a token you can export manually. Session tokens expire after 30 minutes of inactivity, after which you’ll need to sign in again and save a new token. To sign out, use the command [`op signout`](/docs/cli/reference/commands/signout/). ### Optional: Switch between accounts with the `--account` flag If you've added multiple accounts and are using an interactive terminal, 1Password CLI will prompt you to select the account you want to sign in to. Use the arrow keys to select an account, then press the Return key to sign in. In most shells, you can bypass the prompt to select an account using the `--account` flag with your [account shorthand, sign-in address, or ID](#appendix-find-an-account-shorthand-or-id). This option isn't available in PowerShell. For example: **Bash, Zsh, sh, fish:** ```shell eval "$(op signin --account personal)" ``` To always sign in to the same account, set the `OP_ACCOUNT` environment variable to your [account shorthand, sign-in address, or ID](#appendix-find-an-account-shorthand-or-id). **Bash, Zsh, sh:** ```shell export OP_ACCOUNT=my.1password.com ``` **fish:** ```shell set -x OP_ACCOUNT my.1password.com ``` **PowerShell:** ```powershell $Env:OP_ACCOUNT = "my.1password.com" ``` You can sign in to multiple accounts at the same time, then use the `--account` flag to specify which account should execute each command. If you don't specify an account, 1Password CLI will default to the account you most recently signed in to. For example, to sign in to accounts with the shorthands `personal` and `agilebits`: **Bash, Zsh, sh, fish:** ```shell eval "$(op signin --account personal)" && eval "$(op signin --account agilebits)" ``` **PowerShell:** ```powershell Invoke-Expression "$(op signin --account personal)"; Invoke-Expression "$(op signin --account agilebits)" ``` To run the command `op vault list` in the account with the shorthand `personal`: ```shell op vault list --account personal ``` Then to run the same command in the `agilebits` account: ```shell op vault list --account agilebits ``` You can also [specify a custom shorthand](#set-a-custom-account-shorthand) when you add an account. ## Troubleshooting If you've already [turned on the 1Password app integration](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration), you'll need to turn it off before you can add an account on the command line. ## Learn more - [Integrate 1Password CLI with the 1Password desktop app](/docs/cli/app-integration/) - [About the security of the 1Password desktop app integration](/docs/cli/app-integration-security/) ## Appendix: Find an account shorthand or ID 1Password CLI uses account shorthands to refer to each of the accounts you've added. To see all the accounts you've added, their shorthands, and account details, run `op account list`. ```shell op account list #code-result SHORTHAND URL EMAIL USER UUID my https://my.1password.com wendy.c.appleseed@gmail.com A10S... agilebits https://agilebits-inc.1password.com wendy_appleseed@agilebits.com ONJ9... ``` You can use the shorthand, sign-in address, or user ID to refer to a specific account in your commands. --- ## Unlock 1Password CLI with Microsoft :::info This feature is only available as part of the [Unlock with Microsoft beta](https://support.1password.com/cs/sso-azure/). ::: If your 1Password administrator has [configured Unlock with SSO](https://support.1password.com/cs/sso-configure-azure/), you can sign in to 1Password CLI with Microsoft. During the beta period, Unlock with SSO will be available only for Microsoft using the OpenID Connect (OIDC) protocol. Additional platforms, identity providers, and protocols will be available in the future. If the 1Password account you sign in to with Microsoft doesn't allow biometric unlock, you'll be prompted to allow 1Password CLI access to the 1Password app when you sign in. ## Requirements Before you start, you'll need to: 1. [Join your team](https://support.1password.com/cs/sso-get-started-azure#join-your-team), or [switch to unlock with Microsoft](https://support.1password.com/cs/sso-get-started-azure#switch-to-unlock-with-microsoft). 2. Install the nightly release of 1Password for [Mac](https://support.1password.com/betas/?mac), [Windows](https://support.1password.com/betas/?windows), or [Linux](https://support.1password.com/betas/?linux). 3. Sign in to 1Password for [Mac](https://support.1password.com/cs/sso-sign-in-azure#in-the-apps/), [Windows](https://support.1password.com/cs/sso-sign-in-azure#in-the-apps/), or [Linux](https://support.1password.com/cs/sso-sign-in-azure#in-the-apps/) using Microsoft. 4. Install [the latest Password CLI beta build](/docs/cli/reference#beta-builds). ## Step 1: Connect 1Password CLI with the 1Password app To turn on the app integration and set up 1Password CLI to authenticate with Microsoft: **Mac:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 4. Select **Integrate with 1Password CLI**. 5. If you want to authenticate 1Password CLI with your fingerprint, turn on **[Touch ID](https://support.1password.com/touch-id-mac/)** in the app. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ **Windows:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Turn on **[Windows Hello](https://support.1password.com/windows-hello/)** in the app. 4. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 5. Select **Integrate with 1Password CLI**. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ **Linux:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Security](onepassword://settings/security)**. 4. Turn on **[Unlock using system authentication](https://support.1password.com/system-authentication-linux/)**. 5. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 6. Select **Integrate with 1Password CLI**. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ ## Step 2: Sign in with Microsoft Once the 1Password app integration is turned on, open the terminal and type [`op signin`](/docs/cli/get-started#step-3-enter-any-command-to-sign-in). Use the arrow keys to select your Microsoft-enabled account from the list of all accounts added to your 1Password app. 1Password CLI will prompt you to authenticate. ```shell op signin ``` ```shell {2} Select account [Use arrows to move, type to filter] > ACME Corp (acme.1password.com) AgileBits (agilebits.1password.com) Add another account ``` After you sign in for the first time, 1Password CLI will automatically sign in to your most recently used account. If you want to [sign in to a different account](/docs/cli/use-multiple-accounts/), you can use the `--account` flag or an environment variable. ## Get help If the 1Password account you sign in to with Microsoft doesn't allow biometric unlock, you'll be prompted to allow 1Password CLI access to the 1Password app when you sign in. ## Learn more - [About Unlock with Microsoft](https://support.1password.com/cs/sso-azure/) - [Configure Unlock 1Password with Microsoft](https://support.1password.com/cs/sso-configure-azure/) - [Get started with Unlock 1Password with Microsoft](https://support.1password.com/sso-get-started/) - [Sign in to 1Password with Microsoft](https://support.1password.com/cs/sso-sign-in-azure/) - [Link new apps and browsers to unlock with Microsoft](https://support.1password.com/sso-linked-apps-browsers/) - [If you're having trouble unlocking 1Password with SSO](https://support.1password.com/sso-troubleshooting/) --- ## Unlock 1Password CLI with SSO :::info This feature is only available as part of [1Password Unlock with SSO](https://support.1password.com/sso/). ::: If your 1Password administrator has [set up 1Password Unlock with SSO](https://support.1password.com/sso/), you can sign in to 1Password CLI with your identity provider. If the 1Password account you sign in to with SSO doesn't allow biometric unlock, you'll be prompted to allow 1Password CLI access to the 1Password app when you sign in. ## Requirements Before you start, you'll need to: 1. [Join your team](https://support.1password.com/sso-get-started#join-your-team), or [switch to unlock with SSO](https://support.1password.com/sso-get-started#switch-to-unlock-with-sso). 2. Install the latest version of 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. Sign in to 1Password for [Mac](https://support.1password.com/sso-sign-in#in-the-apps/), [Windows](https://support.1password.com/sso-sign-in#in-the-apps/), or [Linux](https://support.1password.com/sso-sign-in#in-the-apps/) using SSO. 4. Install [the latest Password CLI build](/docs/cli/get-started/). ## Step 1: Connect 1Password CLI with the 1Password app To turn on the app integration and set up 1Password CLI to authenticate with your identity provider: **Mac:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 4. Select **Integrate with 1Password CLI**. 5. If you want to authenticate 1Password CLI with your fingerprint, turn on **[Touch ID](https://support.1password.com/touch-id-mac/)** in the app. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ **Windows:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Turn on **[Windows Hello](https://support.1password.com/windows-hello/)** in the app. 4. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 5. Select **Integrate with 1Password CLI**. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ **Linux:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Security](onepassword://settings/security)**. 4. Turn on **[Unlock using system authentication](https://support.1password.com/system-authentication-linux/)**. 5. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 6. Select **Integrate with 1Password CLI**. _[The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.]_ ## Step 2: Sign in with SSO Once the 1Password app integration is turned on, open the terminal and type [`op signin`](/docs/cli/get-started#step-3-enter-any-command-to-sign-in). Use the arrow keys to select your SSO-enabled account from the list of all accounts added to your 1Password app. 1Password CLI will prompt you to authenticate. ```shell op signin ``` ```shell {2} Select account [Use arrows to move, type to filter] > ACME Corp (acme.1password.com) AgileBits (agilebits.1password.com) Add another account ``` After you sign in for the first time, 1Password CLI will automatically sign in to your most recently used account. If you want to [sign in to a different account](/docs/cli/use-multiple-accounts/), you can use the `--account` flag or an environment variable. ## Get help If the 1Password account you sign in to with SSO doesn't allow biometric unlock, you'll be prompted to allow 1Password CLI access to the 1Password app when you sign in. ## Learn more - [Set up 1Password Unlock with SSO](https://support.1password.com/sso/) - [Get started with 1Password Unlock with SSO](https://support.1password.com/sso-get-started/) - [Sign in to 1Password with SSO](https://support.1password.com/sso-sign-in/) - [Link new apps and browsers to unlock with SSO](https://support.1password.com/sso-linked-apps-browsers/) - [If you're having trouble unlocking 1Password with SSO](https://support.1password.com/sso-troubleshooting/) --- ## Manage SSH keys ## Requirements Before you can use 1Password CLI to manage your SSH keys, you'll need to: - [Sign up for 1Password](https://1password.com/pricing/password-manager). - [Install 1Password CLI](/docs/cli/get-started#step-1-install-1password-cli) (`2.20.0` or later). ## Generate an SSH key You can use [`op item create`](/docs/cli/reference/management-commands/item#item-create) with the `ssh` item category to generate a new SSH key. To import an existing SSH key, [use the 1Password desktop app](/docs/ssh/manage-keys#import-an-ssh-key). ```shell op item create --category ssh --title "My SSH Key" ``` 1Password CLI generates an SSH key and saves it as a new item in your built-in Personal, Private, or Employee vault, then prints the key to stdout with the private key redacted. The item includes the key type, private key, public key, and its fingerprint. By default, 1Password CLI creates an Ed25519 key. To create an RSA key instead, use the `--ssh-generate-key` flag to specify `RSA`. Include the number of bits to specify a custom size: 2048, 3072 or 4096 (default). For example, to generate a 2048-bit RSA key: ```shell op item create --category ssh --title "RSA SSH Key" --ssh-generate-key RSA,2048 ``` ## Get a private key To get an SSH key's private key, use [`op read`](/docs/cli/reference/commands/read/) with a [secret reference](/docs/cli/secret-reference-syntax/) for the item's `private key` field. Include the `ssh-format` query parameter with `openssh` to get the private key in the OpenSSH format. ```shell op read "op://Private/ssh keys/ssh key/private key?ssh-format=openssh" #code-result -----BEGIN OPENSSH PRIVATE KEY----- b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABD3rRrf8J ruD0CxZTYfpbTYAAAAEAAAAAEAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIJ5B/GnxX6t9jMwQ G7QE7r5daJLkMKTZhNZhWfvzK2y+AAAAkLgQAivYu/+12/YrZhK5keIAZf4ZgsZsZ2JI2q qbx23PqgO93oGy1iCxXe3kngQL4cM6lwOZPsZPKCinkN6KxEr6RnXqFRHJbMpOiGeZhTuD rjeo77HqFdxDqDeckB77XCKL0Ew28H5JlM/WO31XR3Z4VBAgTe+BQLjrFV8WU5UX38hpBJ PMJyRsK72ZUDDaGQ== -----END OPENSSH PRIVATE KEY----- ``` ## Learn more - [Supported SSH key types](/docs/ssh/manage-keys#supported-ssh-key-types) - [Use 1Password for SSH & Git](/docs/ssh/) - [Manage your SSH keys in the 1Password app](/docs/ssh/manage-keys/) - [Sign your Git commits with SSH](/docs/ssh/git-commit-signing/) --- ## Uninstall 1Password CLI :::warning[caution] Make sure you have access to your Secret Key and account password before removing 1Password account information from your device. ::: ## Step 1: Remove your 1Password account information Your 1Password CLI configuration file contains account details for accounts you've signed in to on the command line using your account password and Secret Key. It does not contain information for accounts you've signed in to using the 1Password desktop app integration. Your config file can be found in one of the following locations: `~/.op/config`, `~/.config/op/config`, or `~/.config/.op/config`. To remove all account information from your config file: ```shell op account forget --all ``` ## Step 2: Uninstall 1Password CLI **Mac:** **homebrew:** To uninstall 1Password CLI with homebrew: ```shell brew uninstall 1password-cli ``` **Manual:** To manually uninstall 1Password CLI, run: ```shell rm /usr/local/bin/op ``` **Windows:** **Scoop:** To uninstall 1Password CLI with Scoop: ```powershell scoop uninstall 1password-cli ``` **winget:** To uninstall 1Password CLI with winget: ```powershell winget uninstall 1password-cli ``` **Manual:** To uninstall 1Password CLI on a Windows PC: 1. Open Powershell **as an administrator**. 2. Run the following command: ```shell Remove-Item -Recurse -Force "C:\Program Files\1Password CLI" ``` **Linux:** To uninstall 1Password CLI on Linux, run: ```shell rm /usr/local/bin/op ``` The 1Password CLI directory and all of its contents will be deleted. --- ## Upgrade to 1Password CLI 2 *Learn how to [upgrade to 1Password CLI 2](#step-1-choose-an-upgrade-strategy) from an earlier version, and [update your scripts](#step-2-update-your-scripts) to the new command syntax.* :::warning[1Password CLI 1 is deprecated] 1Password CLI 1 is deprecated as of **October 1, 2024**. Upgrade to 1Password CLI 2 to avoid disruptions with scripts or integrations that use version 1. ::: ### About 1Password CLI 2 We released version 2 of the 1Password CLI in March 2022. Since then, more than 96% of users have adopted the latest version. 1Password CLI 2 includes a number of changes to the schema to make the tool easier to use as well as new features to help you provision secrets. #### New schema 1Password CLI 2 introduces a noun-verb command structure that groups commands by topic rather than by operation. You can find all available topics with `op --help`, and see the commands avaialble for each topic with `op --help`. Topics include: - [vault](/docs/cli/reference/management-commands/vault/) - [item](/docs/cli/reference/management-commands/item/) - [document](/docs/cli/reference/management-commands/document/) - [user](/docs/cli/reference/management-commands/user/) - [group](/docs/cli/reference/management-commands/group/) - [account](/docs/cli/reference/management-commands/account/) - [connect](/docs/cli/reference/management-commands/connect/) - [events-api](/docs/cli/reference/management-commands/events-api/) Other schema changes include: - The default output is now a human-friendly, tabular schema.Learn how to change the default output to JSON. - The JSON output schema now contains more useful information. - Improved stdin processing allows you to chain more commands together. - The new schema uses flags instead of positional arguments. #### Secrets provisioning To help you provision secrets locally, 1Password CLI 2 allows you to load secrets directly from 1Password in environment variables and configuration files. With secrets provisioning, you can replace your plaintext secrets with references to the secrets stored in 1Password and load them at runtime in your scripts, applications, and other workflows. #### Integrate 1Password CLI with the 1Password desktop app You can sign in to 1Password CLI 2 with the accounts you've added to the 1Password desktop app, then authenticate your accounts on the command line with biometrics. #### Shell plugins To simplify and secure your workflow, 1Password CLI 2 introduces shell plugins that allow you to securely authenticate third-party command-line tools using biometrics. #### Package manager installation 1Password CLI 2 supports easier installation with package managers including Apt, Yum, Alpine, and tar. You can [find all changes in the changelog](https://releases.1password.com/developers/cli/). To share feedback with us, [visit the support community forum](https://1password.community/categories/cli-beta). ## Step 1: Choose an upgrade strategy There are multiple ways to upgrade to 1Password CLI 2. You can upgrade immediately or gradually, depending on your workflow and toolchain. ### Upgrade immediately The quickest way to upgrade to 1Password CLI 2 is to overwrite your existing installation. This is a good option if you have a small team who can upgrade their local installations simultaneously. 1. Use `which op` (or `(Get-Command op).Path` on Windows) to get the directory of the current installation. 2. [Download 1Password CLI 2](https://app-updates.agilebits.com/product_history/CLI2) and move `op` to the same directory, overwriting the existing copy. 3. To verify the installation, check the version number: ```shell op --version ``` 4. [Update your scripts to use the 1Password CLI 2 syntax.](#step-2-update-your-scripts) Make sure everyone on your team upgrades to 1Password CLI 2. After you update your scripts, they won't work with earlier versions of 1Password CLI. ### Upgrade gradually If you're not ready to upgrade immediately, you can use Docker to upgrade individual projects or use both versions of 1Password CLI side-by-side. We will continue to support version 1 for one year after version 2 is released. #### Use Docker to upgrade individual projects If you want to upgrade project by project, you can Dockerize your workflow so that each team member uses the version of 1Password CLI in a Docker image for a specific project. This is a good option for large teams, because it doesn't require each team member to update a local installation. 1. [Use the 1Password CLI Docker image](https://hub.docker.com/r/1password/op) or use your own image and [add the CLI](/docs/cli/get-started/). Your Dockerfile should look like this: ``` FROM 1password/op:2 COPY ./your-script.sh /your-script.sh CMD ["/your-script.sh"] ``` 2. After upgrading to 1Password CLI 2, [update your scripts](#step-2-update-your-scripts) to use the new command syntax. This approach also sets you up to move your scripts to headless environments such as CI/CD pipelines. #### Use both versions of 1Password CLI If your scripts depend on the local installation on each team member's machine, and you still want to migrate gradually, this is your best option. Each team member should do the following: 1. Rename the earlier version of 1Password CLI `op1`. 2. Find and replace all occurences of `op` with `op1`. 3. Install [1Password CLI 2](https://app-updates.agilebits.com/product_history/CLI2) inside your `$PATH`. :::warning[caution] For macOS 1Password CLI 2 has to be moved *exactly* to `/usr/local/bin/op`. For Linux, it is recommended to be moved to `/usr/local/bin/op`. ::: 4. [Update your scripts](#step-2-update-your-scripts) one-by-one to use the new `op`. You can continue to use your current scripts with the earlier version of 1Password CLI installed as `op1`. 5. When you've updated all your scripts and are ready to upgrade, uninstall the earlier version of 1Password CLI. 6. Find and replace all occurrences of `op1` in your scripts to `op`. ## Step 2: Update your scripts If you've been using an earlier version of 1Password CLI in scripts, you'll need to update your scripts to the new syntax. After you install 1Password CLI 2, use the following table to update your scripts. It shows all the updated commands and associated changes to arguments or flags. | Old command | CLI 2 command | Notes | | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [create vault](/docs/cli/v1/reference#create-vault) | [vault create](/docs/cli/reference/management-commands/vault#vault-create) | | | [get vault](/docs/cli/v1/reference#get-vault) | [vault get](/docs/cli/reference/management-commands/vault#vault-get) | | | [edit vault](/docs/cli/v1/reference#edit-vault) | [vault edit](/docs/cli/reference/management-commands/vault#vault-edit) | `--travel-mode=on/off` flag introduced | | [delete vault](/docs/cli/v1/reference#delete-vault) | [vault delete](/docs/cli/reference/management-commands/vault#vault-delete) | allows piped input when the `-` argument is provided | | [list vaults](/docs/cli/v1/reference#list-vaults) | [vault list](/docs/cli/reference/management-commands/vault#vault-list) | by default, lists vaults you have read access toto see all the vaults you can manage, include `--permission manage` | | [list users -\-vault](/docs/cli/v1/reference#list-users) | [vault user list](/docs/cli/reference/management-commands/vault#vault-user-list) | | [add group](/docs/cli/v1/reference#add-group) | [vault group grant](/docs/cli/reference/management-commands/vault#vault-group-grant) | `--permission` flag must be used to specify the permissions to grantgranting allow_viewing, allow_editing and allow_managing is equivalent to granting all permissions`group` and `vault` arguments changed to `--group` and `--vault` flags | | [remove group](/docs/cli/v1/reference#remove-group) | [vault group revoke](/docs/cli/reference/management-commands/vault#vault-group-revoke) | `--permission` flag must be used to specify the permissions to revokerevoking allow_viewing, allow_editing, and allow_managing is equivalent to revoking all permissions`group` and `vault` arguments changed to `--group` and `--vault` flags | | [add user](/docs/cli/v1/reference#add-user) <user> <vault> | [vault user grant](/docs/cli/reference/management-commands/vault#vault-user-grant) | `--permission` flag must be used to specify the permissions to grantgranting allow_viewing, allow_editing and allow_managing is equivalent to granting all permissions`user` and `vault` arguments changed to `--user` and `--vault` flags | | [remove user](/docs/cli/v1/reference#remove-user) <user> <vault> | [vault user revoke](/docs/cli/reference/management-commands/vault#vault-user-revoke) | `--permission` flag must be used to specify the permissions to revokerevoking allow_viewing, allow_editing and allow_managing is equivalent to revoking all permissions`user` and `vault` arguments changed to `--user` and `--vault` flags | | [signin](/docs/cli/v1/reference#signin) <url> | [account add](/docs/cli/reference/management-commands/account#account-add) | for new accounts/urlsthe password can be piped in if email, address, and secret key are provided via flag | | [signin](/docs/cli/v1/reference#signin) -\-list | [account list](/docs/cli/reference/management-commands/account#account-list) | account list will format its output based on output format selection (JSON vs human readable) | | [forget account](/docs/cli/v1/reference#forget) | [account forget](/docs/cli/reference/management-commands/account#account-forget) | new `-—all` flag for forgetting all accounts | | [get account](/docs/cli/v1/reference#get-account) | [account get](/docs/cli/reference/management-commands/account#account-get) | | | [confirm user](/docs/cli/v1/reference#confirm) | [user confirm](/docs/cli/reference/management-commands/user#user-confirm) | allows piped input when the `-` argument is provided | | [create user](/docs/cli/v1/reference#create-user) | [user provision](/docs/cli/reference/management-commands/user#user-provision) | `email` and `name` arguments changed to `--email` and `--name` flags | | [delete user](/docs/cli/v1/reference#delete-user) | [user delete](/docs/cli/reference/management-commands/user#user-delete) | allows piped input when the `-` argument is provided | | [edit user](/docs/cli/v1/reference#edit-user) | [user edit](/docs/cli/reference/management-commands/user#user-edit) | allows piped input when the `-` argument is provided | | [reactivate user](/docs/cli/v1/reference#reactivate) | [user reactivate](/docs/cli/reference/management-commands/user#user-reactivate) | allows piped input when the `-` argument is provided | | [suspend user](/docs/cli/v1/reference#suspend) | [user suspend](/docs/cli/reference/management-commands/user#user-suspend) | `--deauthorize-devices-after` flag accepts any duration unit, not just seconds | | [list users](/docs/cli/v1/reference#list-users) | [user list](/docs/cli/reference/management-commands/user#user-list) | | | [get user](/docs/cli/v1/reference#get-user) | [user get](/docs/cli/reference/management-commands/user#user-get) | added `-—me` flag to get the currently authenticated user `—publickey` changed to `—public-key` | | [create connect server](/docs/cli/v1/reference#create-connect-server) | [connect server create](/docs/cli/reference/management-commands/connect#connect-server-create) | add `—-server` flag instead of using an argument for specifying the related server | | [delete connect server](/docs/cli/v1/reference#delete-connect-server) | [connect server delete](/docs/cli/reference/management-commands/connect#connect-server-delete) | allows piped input when the `-` argument is provided | | [edit connect server](/docs/cli/v1/reference#edit-connect-server) | [connect server edit](/docs/cli/reference/management-commands/connect#connect-server-edit) | | | [list connect servers](/docs/cli/v1/reference#list-connect-servers) | [connect server list](/docs/cli/reference/management-commands/connect#connect-server-list) | | | - | [connect server get](/docs/cli/reference/management-commands/connect#connect-server-get) | | | [create connect token](/docs/cli/v1/reference#create-connect-token) | [connect token create](/docs/cli/reference/management-commands/connect#connect-token-create) | | | [delete connect token](/docs/cli/v1/reference#delete-connect-token) | [connect token delete](/docs/cli/reference/management-commands/connect#connect-token-delete) | | | [edit connect token](/docs/cli/v1/reference#edit-connect-token) | [connect token edit](/docs/cli/reference/management-commands/connect#connect-token-edit) | argument name changed from `jti` to `token` | | [list connect tokens](/docs/cli/v1/reference#list-connect-tokens) | [connect token list](/docs/cli/reference/management-commands/connect#connect-token-list) | ConnectVault.ACL is now displayed in lowercase_with_underscores | | [add connect server](/docs/cli/v1/reference#add-connect-server) | [connect vault grant](/docs/cli/reference/management-commands/connect#connect-vault-grant) | `server` and `vault` arguments changed to `--server` and `--vault` flags | | [remove connect server](/docs/cli/v1/reference#remove-connect-server) | [connect vault revoke](/docs/cli/reference/management-commands/connect#connect-vault-revoke) | `server` and `vault` arguments changed to `--server` and `--vault` flags | | [manage connect add group](/docs/cli/v1/reference#manage-connect-add) | [connect group grant](/docs/cli/reference/management-commands/connect#connect-group-grant) | `server` and `group` arguments changed to `--server` and `--group` flags | | [manage connect remove group](/docs/cli/v1/reference#manage-connect-remove) | [connect group revoke](/docs/cli/reference/management-commands/connect#connect-group-revoke) | `server` and `group` arguments changed to `--server` and `--group` flags | [create item](/docs/cli/v1/reference#create-item) | [item create](/docs/cli/reference/management-commands/item#item-create) | `--template` flag to specify item template file replaces encode item as an argument`category` argument changed to `--category` flagTemplate JSON format has changed. [Learn more about the new format.](#appendix-json) | | [delete item](/docs/cli/v1/reference#delete-item) | [item delete](/docs/cli/reference/management-commands/item#item-delete) | allows piped input when the `-` argument is provided | | [edit item](/docs/cli/v1/reference#edit-item) | [item edit](/docs/cli/reference/management-commands/item#item-edit) | new `--tags`, `--title`, `--url` flags | | [get item](/docs/cli/v1/reference#get-item) | [item get](/docs/cli/reference/management-commands/item#item-get) | | | [list items](/docs/cli/v1/reference#list-items) | [item list](/docs/cli/reference/management-commands/item#item-list) | | | [list templates](/docs/cli/v1/reference#list-templates) | [item template list](/docs/cli/reference/management-commands/item#item-template-list) | | | [get template](/docs/cli/v1/reference#get-template) | [item template get](/docs/cli/reference/management-commands/item#item-template-get) | | | [create group](/docs/cli/v1/reference#create-group) | [group create](/docs/cli/reference/management-commands/group#group-create) | | | [delete group](/docs/cli/v1/reference#delete-group) | [group delete](/docs/cli/reference/management-commands/group#group-delete) | allows piped input when the `-` argument is provided | | [edit group](/docs/cli/v1/reference#edit-group) | [group edit](/docs/cli/reference/management-commands/group#group-edit) | allows piped input when the `-` argument is provided | | [list groups](/docs/cli/v1/reference#list-groups) | [group list](/docs/cli/reference/management-commands/group#group-list) | | | [get group](/docs/cli/v1/reference#get-group) | [group get](/docs/cli/reference/management-commands/group#group-get) | | | [add user](/docs/cli/v1/reference#add-user) <user> <group> | [group user grant](/docs/cli/reference/management-commands/group#group-user-grant) | `user` and `group` arguments changed to `--user` and `--group` flags | | [remove user](/docs/cli/v1/reference#remove-user) <user> <group> | [group user revoke](/docs/cli/reference/management-commands/group#group-user-revoke) | `user` and `group` args changed to `--user` and `--group` flags | | [op list users --group <group>](/docs/cli/v1/reference#list-users) | [group user list](/docs/cli/reference/management-commands/group#group-user-list) | op list users `--group GROUP` still works | | [delete trash](/docs/cli/v1/reference#delete-trash) | - | deprecated | | [create document](/docs/cli/v1/reference#create-document) | [document create](/docs/cli/reference/management-commands/document#document-create) | `--filename` flag changed to `--file-name` flag | | [edit document](/docs/cli/v1/reference#edit-document) | [document edit](/docs/cli/reference/management-commands/document#document-edit) | `--filename` flag changed to `--file-name` flag | | [list documents](/docs/cli/v1/reference#list-documents) | [document list](/docs/cli/reference/management-commands/document#document-list) | | | [get document](/docs/cli/v1/reference#get-document) | [document get](/docs/cli/reference/management-commands/document#document-get) | | | [delete document](/docs/cli/v1/reference#delete-document) | [document delete](/docs/cli/reference/management-commands/document#document-delete) | | | [create integration events-api](/docs/cli/v1/reference#create-integration-events-api) | [events-api create](/docs/cli/reference/management-commands/events-api#events-api-create) | | | [list events](/docs/cli/v1/reference#list-events) | - | Use [1Password Events API](/docs/events-api/) instead. | | [encode](/docs/cli/v1/reference#encode) | - | deprecated, use `create item --template=file.json` instead | | [get totp](/docs/cli/v1/reference#get-totp) | [item get --otp](/docs/cli/reference/management-commands/item#item-get) | | ## Appendix: Change default output to JSON {#json-default} The default output format for 1Password CLI 2 is a human-readable, tabular schema. You can change the default to machine-readable JSON in two ways: - For a single command, include the `--format json` flag with your command. For example, `op item get --format json`. - To always default to JSON, set the `$OP_FORMAT` environment variable to `json`. ## Appendix: Item JSON template {#appendix-json} You can expect to see several formatting improvements and field name changes in 1Password CLI 2 [item JSON templates](/docs/cli/item-template-json/). **Old template** ```json { "fields": [ { "designation": "username", "name": "username", "type": "T", "value": "" }, { "designation": "password", "name": "password", "type": "P", "value": "" } ], "notesPlain": "", "passwordHistory": [], "sections": [] } ``` **New template** ```json { "title": "", "category": "LOGIN", "fields": [ { "id": "username", "type": "STRING", "purpose": "USERNAME", "label": "username", "value": "" }, { "id": "password", "type": "CONCEALED", "purpose": "PASSWORD", "label": "password", "value": "" }, { "id": "notesPlain", "type": "STRING", "purpose": "NOTES", "label": "notesPlain", "value": "" } ] } ``` This is how 1Password CLI 1 template fields correspond to 1Password CLI 2: **Item** | 1Password CLI 1 | 1Password CLI 2 | Notes | | --------------- | --------------- | ----------------------------------- | | `uuid` | | | | `templateUuid` | `category` | | | `details` | - | replaced by `sections` and `fields` | **Section** | 1Password CLI 1 | 1Password CLI 2 | Notes | | --------------- | --------------- | ---------------- | | `name` | `id` | | | `title` | `label` | | | `fields` | - | moved separately | **Field** | 1Password CLI 1 | 1Password CLI 2 | | --------------- | --------------- | | `n` | `id` | | `k` | `type` | | `t` | `label` | | `v` | `value` | | - | `section` | ## Get help If you need help upgrading to 1Password CLI 2, [contact 1Password Support](mailto:integrations@1password.com) or join our [Developer Slack workspace](https://developer.1password.com/joinslack) and ask a question in the `#cli` channel. ## Learn more - [Get started with 1Password CLI 2](/docs/cli/get-started/) - [1Password CLI 2 release notes](https://releases.1password.com/developers/cli/) --- ## 1Password CLI use cases # Use cases 1Password CLI allows you to securely provision secrets in development environments, use scripts to manage items and provision team members at scale, and authenticate with biometrics in the terminal. ## Eliminate plaintext secrets in code{#secrets} _[An item open in the 1Password app with the option to copy a secret reference selected.]_ With 1Password CLI, you can store secrets securely in your 1Password vaults then use [secret references](/docs/cli/secret-references/) to load them into [environment variables](/docs/cli/secrets-environment-variables/), [configuration files](/docs/cli/secrets-config-files/), and [scripts](/docs/cli/secrets-scripts/) without putting any plaintext secrets in code. Secret references are dynamic – if you update your credentials in 1Password, the changes will be reflected in your scripts without needing to update the script directly. You can also [use variables within secret references](/docs/cli/secret-reference-syntax#externally-set-variables) to pass different sets of secrets for different environments using the same file. For example, you can use a secret reference in place of your plaintext GitHub Personal Access Token in a `github.env` file: _[An environment file using a plaintext secret and the same file using a secret reference.]_ Then use [`op run`](/docs/cli/reference/commands/run/) to pass the file with the token provisioned from 1Password to your application or script when you need it. The script will run with the token provisioned, without the token ever appearing in plaintext. Learn more - [Get started with secret references](/docs/cli/secret-references/) - [Load secrets into the environment](/docs/cli/secrets-environment-variables/) - [Load secrets into config files](/docs/cli/secrets-config-files/) - [Load secrets into scripts](/docs/cli/secrets-scripts/) ## Automate administrative tasks{#automate} _[1password.com open to show the people who have access to a vault alongside a terminal window displaying the same information.]_ With 1Password CLI, IT administrators can set up scripts to automate common tasks, like [provisioning users](/docs/cli/provision-users/), [managing permissions](/docs/cli/grant-revoke-vault-permissions/), [managing items](/docs/cli/reference/management-commands/item/), and generating custom reports. For example, this script will loop through each vault the person who runs the script has access to and provide: - the vault name - the number of items in the vault - the last time the vault's contents were updated - the users and groups that have access to the vault along with their permissions ```bash title="vault_details.sh" #!/usr/bin/env bash for vault in $(op vault list --format=json | jq --raw-output '.[] .id') do echo "" echo "Vault Details" op vault get $vault --format=json | jq -r '.|{name, items, updated_at}' sleep 1 echo "" echo "Users" op vault user list $vault sleep 1 echo "" echo "Groups" op vault group list $vault sleep 1 echo "" echo "End of Vault Details" sleep 2 clear echo "" echo "" done ``` Learn more See our [repository of example 1Password CLI scripts](https://github.com/1Password/solutions) for inspiration for your own projects. You'll find scripts that can help you: - [Provision new users from a CSV](https://github.com/1Password/solutions/tree/main/1password/scripted-provisioning/) - [Audit or manage existing users](https://github.com/1Password/solutions/tree/main/1password/user-management/) - [Manage your vaults and groups](https://github.com/1Password/solutions/tree/main/1password/account-management/) - [Create, update, and share items](https://github.com/1Password/solutions/tree/main/1password/item-management/) To learn more about how to accomplish these tasks with 1Password CLI, see the following guides: - [Create items](/docs/cli/item-create/) - [Add and remove team members](/docs/cli/provision-users/) - [Grant and revoke vault permissions](/docs/cli/grant-revoke-vault-permissions/) ## Sign in to any CLI with your fingerprint{#shell-plugins} With our [shell plugin ecosystem](/docs/cli/shell-plugins/), you can use 1Password to securely authenticate all your command-line tools. Store your CLI access credentials in your 1Password vaults then sign in to your CLIs with your fingerprint instead of entering your credentials manually or storing them in an unencrypted format on your computer. Shell plugins unlock the ability to securely share credentials between team members. Store a token in a shared 1Password vault, and all people with access to the vault will be able to sign in with them. And you can use shell plugins across [multiple environments](/docs/cli/shell-plugins/environments/), so you don't have to spend time signing in and out between projects. For example, the [ngrok shell plugin](/docs/cli/shell-plugins/ngrok/) can securely tunnel the local app to the internet for a web development project running on your computer. The ngrok authtoken is not stored anywhere on the computer. When the ngrok CLI is run, the shell plugin provisions the authtoken as an environment variable for the ngrok binary to consume, and when the process exits, the environment variable is cleared. Learn more Get started with one of our most popular shell plugins: [_[]_ GitHub](/docs/cli/shell-plugins/github/) [_[]_ AWS](/docs/cli/shell-plugins/aws/) [_[]_ Homebrew](/docs/cli/shell-plugins/homebrew/) [_[]_ GitLab](/docs/cli/shell-plugins/gitlab/) [_[]_ OpenAI](/docs/cli/shell-plugins/openai/) [_[]_ postgresql](/docs/cli/shell-plugins/postgresql/) [_[]_ Terraform](/docs/cli/shell-plugins/terraform/) [_[]_ DigitalOcean](/docs/cli/shell-plugins/digitalocean/) [_[]_ Heroku](/docs/cli/shell-plugins/heroku/) [_[]_ ngrok](/docs/cli/shell-plugins/ngrok/) [_[]_ CircleCI](/docs/cli/shell-plugins/circleci/) [_[]_ Vault](/docs/cli/shell-plugins/hashicorp-vault/) Or choose a plugin from [our library of more than 40 command-line tools](/docs/cli/shell-plugins/) to get started with. If the tool you want to use isn't supported yet, you can [build your own plugin](/docs/cli/shell-plugins/contribute/). You can also: - [Test shell plugins](/docs/cli/shell-plugins/test/) - [Use shell plugins to switch between environments](/docs/cli/shell-plugins/environments/) - [Use shell plugins with multiple accounts](/docs/cli/shell-plugins/multiple-accounts/) --- ## Use 1Password CLI with multiple accounts # Use multiple 1Password accounts with 1Password CLI When you [use the 1Password desktop app integration to sign in to 1Password CLI](/docs/cli/app-integration/), you can access any 1Password account you've added to the app on the command line. By default, all 1Password CLI commands are executed with the account you most recently signed in to, unless an account is specified with the [`--account` flag](#specify-an-account-per-command-with-the---account-flag). ## Choose an account to sign in to with `op signin` To choose an account to sign in to, run [`op signin`](/docs/cli/reference/commands/signin/) and select the account you want to sign in to from the list of accounts added to your 1Password app. ```shell {2} op signin #code-result Select account [Use arrows to move, type to filter] > ACME Corp (acme.1password.com) AgileBits (agilebits.1password.com) Add another account ``` If you don't see the account you want to use, you may need to [add it to the 1Password app](https://support.1password.com/add-account/). ## Specify an account per command with the `--account` flag You can execute a command with a specific account by including the `--account` flag along with the account's [sign-in address (with or without https://) or ID](#find-an-account-sign-in-address-or-id). For example, to get a list of all vaults in an account with the sign-in address `my.1password.com`: ```shell op vault ls --account my.1password.com ``` You can use the `--account` flag to specify different accounts in scripts. For example: ```shell PASSWORD_1="$(op read --account agilebits-inc.1password.com op://my-vault/some-item/password)" PASSWORD_2="$(op read --account acme.1password.com op://other-vault/other-item/password)" ``` ## Set an account with the `OP_ACCOUNT` environment variable If you only want to sign in to a specific account, set the `OP_ACCOUNT` environment variable to the account's [sign-in address or ID](#find-an-account-sign-in-address-or-id). You can also use this to specify an account in scripts. **Bash, Zsh, sh:** ```shell export OP_ACCOUNT=my.1password.com ``` **fish:** ```shell set -x OP_ACCOUNT my.1password.com ``` **PowerShell:** ```powershell $Env:OP_ACCOUNT = "my.1password.com" ``` ## Find an account sign-in address or ID To find details about all the accounts you've added to the 1Password app, run `op account list`. ```shell op account list #code-result $ op account list URL EMAIL USER ID my.1password.com wendy.c.appleseed@gmail.com JDFU... agilebits-inc.1password.com wendy_appleseed@agilebits.com ASDU... ``` You can use the sign-in address listed under `URL` or the unique identifier listed under `USER ID` to refer to the account. ## Learn more - [Use the 1Password desktop app to sign in to 1Password CLI](/docs/cli/app-integration/) --- ## User states When you fetch information about users with [`op user list`](/docs/cli/reference/management-commands/user#user-list) or [`op user get`](/docs/cli/reference/management-commands/user#user-get), 1Password CLI returns each person's current account state. | User state | Description | | ------------------ | ------------------------------------------------------------ | | `ACTIVE` | The user is active. | | `RECOVERY_STARTED` | [Account recovery](/docs/cli/recover-users) has been started for the user. | | `RECOVERY_ACCEPTED` | The user has created their new account password and is waiting to be [confirmed again by an administrator](https://support.1password.com/recovery#complete-recovery). | | `SUSPENDED` | The user is suspended. | | `TRANSFER_STARTED` | The user has been provisioned, but hasn't set up their account. | | `TRANSFER_SUSPENDED` | The user was provisioned and didn't set up their account before they were deprovisioned. | --- ## Get started with 1Password CLI 1 :::warning[Upgrade to 1Password CLI 2] 1Password CLI 1 is deprecated as of **October 1, 2024**. Scripts and integrations that use version 1 will no longer work as expected. [Upgrade to 1Password CLI 2](/docs/cli/upgrade/) to maintain uninterrupted access and compatibility with the latest features. ::: The first time you sign in to a 1Password account with 1Password CLI, you'll need your [sign-in address](https://support.1password.com/sign-in-troubleshooting#if-youre-asked-for-a-sign-in-address), [Secret Key](https://support.1password.com/secret-key/), email address, and account password. Your sign-in address is the URL you use to sign in to your account on 1Password.com (`my.1password.com` in this example). The subdomain for your sign-in address (`my` in this example) will be the shorthand 1Password CLI uses to refer to your account. To specify a custom shorthand, use `--shorthand ` on your first sign-in. To sign in to an account for the first time: 1. Use `op signin` with your sign-in address and email address: ```shell op signin my.1password.com wendy_appleseed@example.com ``` 2. Enter your [Secret Key](https://support.1password.com/secret-key/), then enter your account password. 3. Use the `eval` (Mac, Linux) or `Invoke-Expression` (Windows) command returned by the tool to save your session token to an environment variable automatically. Or run the `export` command to set it manually. On Mac and Linux: ```shell eval $(op signin my) ``` On Windows: ```shell Invoke-Expression $(op signin my) ``` The `eval` and `Invoke-Expression` commands use your account shorthand as an argument to specify which account to sign in to. In the example above, the shorthand `my` refers to `my.1password.com`. Now that you have a session token, you can start using 1Password CLI. Session tokens expire after 30 minutes of inactivity, after which you'll need to sign in again and save a new token. After the first time you sign in to an account, you can use a shorter command to sign in again: ```shell op signin ``` If you've added multiple accounts to 1Password CLI, you can choose which account to sign in to by specifying the shorthand. For example: ```shell op signin my ``` If no shorthand is provided, 1Password CLI will default to the most recently used account. To see all of the accounts you've previously authenticated and their shorthands: ```shell op signin --list ``` ## Learn more You can use 1Password CLI to work with users, vaults, and items. For example, here's how to upload a document to your Private vault: ```shell op create document readme.txt --vault Private ``` To see a list of all the items in your Shared vault: ```shell op list items --vault Shared ``` The output will show the [UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) of the items. To get the details of an item: ```shell op get item WestJet ``` You can use names or UUIDs in commands that take any user, vault, or item as an argument. Use UUIDs because they'll never change, so you can be sure you're always referring to the same object. It's also faster and more efficient. ```shell op get item nqikpd2bdjae3lmizdajy2rf6e ``` You can get details of just the fields you want. For one field, 1Password CLI returns a simple string: ```shell op get item nqikpd2bdjae3lmizdajy2rf6e --fields password 5ra3jOwnUsXVjx5GL@FX2d7iZClrrQDc ``` For multiple fields, specify them in a comma-separated list. 1Password CLI returns a JSON object: ```shell op get item nqikpd2bdjae3lmizdajy2rf6e --fields username,password {"username": "wendy_appleseed", "password": "5ra3jOwnUsXVjx5GL@FX2d7iZClrrQDc"} ``` ## Parse and manipulate JSON output with jq Every `op` command outputs in one of two formats: a simple string, like a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), or JSON. To parse and manipulate JSON output, we recommend the [command-line tool jq](https://stedolan.github.io/jq). To use jq to parse a Login item called "WestJet" and retrieve the password: ```shell op get item WestJet | jq '.details.fields[] | select(.designation=="password").value' ``` To use jq to manipulate a Login item template, set the username value to "wendy", and save the item in your Private vault: On Mac and Linux: ```shell umask 077 # Prevent others from reading your template file ``` ```shell op get template login | \ jq '(.fields[] | select(.designation == "username")).value = "wendy"' > login.json op create item login --template login.json --title "My New Item" rm login.json ``` On Windows: ```shell cd "$HOME" # Prevent others from reading your template file ``` ```shell op get template login | \ jq '(.fields[] | select(.designation == "username")).value = "wendy"' > login.json op create item login --template login.json --title "My New Item" rm login.json ``` [Learn more about jq.](https://stedolan.github.io/jq/tutorial/) ## Get help To check for updates to 1Password CLI: ```shell op update ``` If a newer version is available, 1Password CLI can download it for you. You can see a list of all commands with `op --help`, or learn about a specific commands with `op --help`. --- ## 1Password CLI 1 reference :::warning[Upgrade to 1Password CLI 2] 1Password CLI 1 is deprecated as of **October 1, 2024**. Scripts and integrations that use version 1 will no longer work as expected. [Upgrade to 1Password CLI 2](/docs/cli/upgrade/) to maintain uninterrupted access and compatibility with the latest features. ::: Sign in to an account to get started. Run `op signin --help` to learn more. ### How to specify objects You can specify all objects by name or UUID. You can also specify some objects by other attributes: - **Items**: item link - **Login or Password items**: domain name - **Users**: email address When you specify an item by name or domain, there may be more than one item that matches. To be more specific, use the `--vault` option to only look in one vault at a time, or use a unique ID (UUID) instead. Looking up an item (such as a Connect server or vault) by ID is more efficient than using the name. ### Cache item and vault information 1Password CLI can use its daemon process to cache items, vault information, and the keys to access information in an account. To use the cache, use the `--cache` option with a command. When working with items, the cache is most effective after it has a list of the items in a vault. The daemon stores encrypted information in memory using the same encryption methods as on 1Password.com. It can read the information to pass to 1Password CLI but can’t decrypt it. 1Password CLI starts the daemon automatically and it terminates itself after 24 hours of inactivity. ### Use alternative character encoding By default, 1Password CLI processes input and output with UTF-8 encoding. You can use an alternative character encoding with the `--encoding` option. Supported alternative character encoding types: - `gbk` - `shift-jis` ### Commands - [add](#add): Grant access to groups or vaults - [completion](#completion): Generate shell completion information - [confirm](#confirm): Confirm a user - [create](#create): Create an object - [delete](#delete): Remove an object - [edit](#edit): Edit an object - [encode](#encode): Encode the JSON needed to create an item - [forget](#forget): Remove a 1Password account from this device - [get](#get): Get details about an object - [list](#list): List objects and events - [manage](#manage): Manage group access to 1Password integrations - [reactivate](#reactivate): Reactivate a suspended user - [remove](#remove): Revoke access to groups or vaults - [signin](#signin): Sign in to a 1Password account - [signout](#signout): Sign out of a 1Password account - [suspend](#suspend): Suspend a user - [update](#update): Check for and download updates ### Usage ```shell op [command] [options] ``` ### Global options ``` --account shorthand use the account with this shorthand --cache store and use cached information --config directory use this configuration directory -h, --help get help with a command --session token authenticate with this session token ``` ### Get help For help with any command, use the `--help` option: ```shell op [subcommand] --help ``` - - - - - - - - - - - - - - - - - - ## *add* ### Subcommands {#add-subcommands} - [add connect](#add-connect): Grant access to vaults to 1Password Secrets Automation - [add group](#add-group): Grant a group access to a vault - [add user](#add-user): Grant a user access to a vault or group ### Related commands {#add-related-commands} - [edit](#edit): Edit an object - [remove](#remove): Revoke access to groups or vaults ## *add connect* ### Subcommands {#add-connect-subcommands} - [add connect server](#add-connect-server): Grant a Connect server access to a vault ## *add connect server* Grant a Connect server access to a vault. ```shell op add connect server [flags] ``` ### Related commands {#add-connect-server-related-commands} - [create connect token](#create-connect-token): Issue a token for a 1Password Connect server ## *add group* Grant a group access to a vault. ```shell op add group [flags] ``` ## *add user* Grant a user access to a vault or group. ```shell op add user [ | ] [flags] ``` ### Options for add user ``` --role role set the user's role in a group (member or manager) (default "member") ``` ## *completion* Generate shell completion information for 1Password CLI. ```shell op completion [flags] ``` ### How completion works If you use Bash or Zsh, you can add shell completion for 1Password CLI. With completions loaded, after you start typing an `op` command, press Tab to see available commands and options. #### Load shell completion information for Bash To always load the completion information for Bash, add this to your `.bashrc` file: ```shell source <(op completion bash) ``` To use shell completion in Bash, you’ll need the `bash-completion` package. #### Load shell completion information for Zsh To always load the completion information for Zsh, add this to your `.zshrc` file: ```shell eval "$(op completion zsh)"; compdef _op op ``` ## *confirm* Confirm users. ```shell op confirm [ | --all] ``` ### Options for confirm ``` --all confirm all unconfirmed users ``` ### Related commands {#confirm-related-commands} - [create user](#create-user): Create a user ## *create* ### Subcommands {#create-subcommands} - [create connect](#create-connect): Create 1Password Connect servers and tokens - [create document](#create-document): Create a document - [create group](#create-group): Create a group - [create integration](#create-integration): Create an integration - [create item](#create-item): Create an item - [create user](#create-user): Create a user - [create vault](#create-vault): Create a vault ## *create connect* ### Subcommands {#create-connect-subcommands} - [create connect server](#create-connect-server): Set up a 1Password Connect server - [create connect token](#create-connect-token): Issue a token for a 1Password Connect server ## *create connect server* Add a 1Password Connect server to your account and generate a credentials file for it. ```shell op create connect server [flags] ``` ### Options for create connect server ``` --vaults vaults grant the Connect server access to these vaults ``` ### How create connect server works The `1password-credentials.json` file is saved in the current directory. ### Related commands {#create-connect-server-related-commands} - [create connect token](#create-connect-token): Issue a token for a 1Password Connect server - [manage connect add](#manage-connect-add): Grant access to manage Secrets Automation - [manage connect remove](#manage-connect-remove): Revoke access to manage Secrets Automation ## *create connect token* Issue a new token for an Connect server. ```shell op create connect token [flags] ``` ### Options for create connect token ``` --expires-in duration set how the long token is valid for --vault vault grant access to this vault ``` ### How create connect token works Returns a token. You can only grant a token access to a vault that the server has access to and only the permissions the server has for it. By default, the `--vault` option grants the same permissions as the server. You can further limit the permissions a token has to read-only or write-only by adding a comma and `r` or `w` after the vault specification. For example: ```shell op create connect token "Dev" "Dev k8s token" --vault Kubernetes,r op create connect token "Prod" "Prod: Customer details" --vault Customers,w ``` ### Related commands {#create-connect-token-related-commands} - [manage connect add](#manage-connect-add): Grant access to manage Secrets Automation - [manage connect remove](#manage-connect-remove): Revoke access to manage Secrets Automation ## *create document* Create a document. ```shell op create document [flags] ``` ### Options for create document ``` --filename name set the file's name --tags tags add one or more tags (comma-separated) to the item --title title set the item's title --vault vault save the document in this vault ``` ### How create document works When you create a document, a JSON object containing its UUID is returned. The document is saved to the Private or Personal vault unless you specify another with the `--vault` option. #### Create a file from standard input To create the file contents from standard input (`stdin`), enter a hyphen (`-`) instead of a path. You can use the `--filename` option to change the name of the file. ### Examples for create document Create a document from standard input: ```shell cat auth.log.* | op create document - --title "Authlogs 2020-06" --file-name "auth.log.2020.06" ``` ## *create group* Create a group. ```shell op create group [flags] ``` ### Options for create group ``` --description description set the group's description ``` ### How create group works When you create a group, a JSON object containing its UUID is returned. ## *create integration* ### Subcommands {#create-integration-subcommands} - [create integration events-api](#create-integration-events-api): Create an Events API integration ## *create integration events-api* Create an Events API integration token. Print the Events API integration token when successful. ```shell op create integration events-api [flags] ``` ### Options for create integration events-api ``` --expires-in duration set how the long the integration token is valid for --features features set the comma-sepparated list of features the integration token can be used for. Options: `signinattempts`, `itemusages` ``` ## create item Create an item. ```shell op create item { --template | [...] | } [flags] ``` ### Options for create item ``` --generate-password[=recipe] give the item a randomly generated password --tags tags add one or more tags (comma-separated) to the item --template string specify the filepath to read an item template from --title title set the item's title --url URL set the URL associated with the item --vault vault save the item in this vault ``` ### How create item works Create an item using assignment statements or with a 1Password JSON object template. When you create an item, a JSON object containing its UUID is returned. The item is saved to the Private or Personal vault unless you specify another with the `--vault` option. #### Create an item with assignment statements Use an assignment statement to set a field's value: ``` [
.]= ``` You can omit spaces when you specify the section or field name. You can also refer to the field by its JSON short name (`name` or `n`). ``` phonetollfree=012066188656 ``` The section is optional unless multiple sections have a field with the same name. ``` testingserver.address=db.local.1password.com developmentserver.address=db.dev.1password.com ``` You can't make a new custom section using an assignment statement. :::important Note If you can't trust other users or processes on your system, use `op create item --template=file.json` instead. ::: #### Generate a password Use the `--generate-password` option to generate and set a random password for a Login or Password item. By default, it will create a 32-character password made up of letters, numbers, and symbols. You can customize the password with a password recipe. Specify the password length and which character types to use in a comma-separated list. Ingredients are: - `letters` for uppercase and lowercase letters - `digits` for numbers - `symbols` for special characters (`!@.-_*`) - `1`-`64` for password length #### Create an item with a template If you want to create an item with custom sections or fields, use a JSON object template. Download and edit a template for the category of item you want to create. Run `op help get template` for a list of template categories. To create an item using a template: 1. Get a template for the category of item you want to create, and save it to a file: ```shell op get template "Login" > login.json ``` 2. Edit the template to add your information. 3. Create the item from the template file: ```shell op create item --template=login.json Login ``` 4. When you’re finished, remove the template file. You can use a tool like [jq](https://stedolan.github.io/jq/) to reformat JSON to make it easier to read. If you were using `op encode` previously when creating items, upgrade to the more secure `create item --template=file.json`. It skips the need to encode the file. If you use both a template and assignment statements in the same command, the assignment statements overwrite the template's values. ### Related commands {#create-item-related-commands} - [encode](#encode): Encode the JSON needed to create an item - [get template](#get-template): Get an item template - [list templates](#list-templates): Get a list of templates ## *create user* Create a new user. ```shell op create user [flags] ``` ### Options for create user ``` --language language set the user's account language (default "en") ``` ### Related commands {#create-user-related-commands} - [confirm](#confirm): Confirm a user ## *create vault* Create a new vault. ```shell op create vault [flags] ``` ### Options for create vault ```shell --allow-admins-to-manage true|false set whether admins can manage vault access --description description set the vault's description --icon string set the vault icon ``` ### How create vault works Valid icon keywords are: - airplane - application - art-supplies - bankers-box - brown-briefcase - brown-gate - buildings - cabin - castle - circle-of-dots - coffee - color-wheel - curtained-window - document - doughnut - fence - galaxy - gears - globe - green-backpack - green-gem - handshake - heart-with-monitor - house - id-card - jet - large-ship - luggage - plant - porthole - puzzle - rainbow - record - round-door - sandals - scales - screwdriver - shop - tall-window - treasure-chest - vault-door - vehicle - wallet - wrench ## *delete* ### Subcommands {#delete-subcommands} - [delete connect](#delete-connect): Remove 1Password Connect servers and tokens - [delete document](#delete-document): Delete or archive a Document - [delete group](#delete-group): Remove a group - [delete item](#delete-item): Delete or archive an item - [delete trash](#delete-trash): Delete trash - [delete user](#delete-user): Completely remove a user - [delete vault](#delete-vault): Remove a vault ## *delete connect* ### Subcommands {#delete-connect-subcommands} - [delete connect server](#delete-connect-server): Remove a 1Password Connect server - [delete connect token](#delete-connect-token): Revoke a token for a Connect server ## *delete connect server* Remove a 1Password Connect server. ```shell op delete connect server [flags] ``` ### How delete connect server works The credentials file and all the tokens for the server will no longer be valid. ## *delete connect token* Revoke a token for a Connect server. ```shell op delete connect token [flags] ``` ### Options for delete connect token ``` --server string only look for tokens for this 1Password Connect server ``` ### Related commands {#delete-connect-token-related-commands} - [create connect token](#create-connect-token): Issue a token for a 1Password Connect server ## *delete document* Permanently delete a document. Use the `--archive` option to move it to the Archive instead. ```shell op delete document [flags] ``` ### Options for delete document ``` --archive move the document to the Archive --vault vault look for the document in this vault ``` ### How delete document works #### Specify items on standard input The command treats each line of information on standard input (`stdin`) as an object specifier. Run `op help` to learn more about how to specify objects. The input can also be a list or array of JSON objects. The command will get an item for any object that has a UUID key. This is useful for passing information from one `op` command to another. ### Examples for delete document Permanently delete a document: ```shell op delete document "2019 Contracts" ``` Move a document to the Archive: ```shell op delete document "2019 Contracts" --archive ``` ## *delete group* Remove a group. ```shell op delete group [flags] ``` ## *delete item* Permanently delete an item. Use the `--archive` option to move it to the Archive instead. ```shell op delete item [flags] ``` ### Options for delete item ```shell --archive move the item to the Archive --vault vault look for the item in this vault ``` ### How delete item works #### Specify items on standard input The command treats each line of information on standard input (`stdin`) as an object specifier. Run `op help` to learn more about how to specify objects. The input can also be a list or array of JSON objects. The command will get an item for any object that has a UUID key. This is useful for passing information from one `op` command to another. ### Examples for delete item Permanently delete an item: ```shell op delete item "Defunct Login" ``` Move an item to the Archive: ```shell op delete item "Defunct Login" --archive ``` ## *delete trash* You can permanently delete an item with `op delete ` or to move it to the Archive, use `op delete item --archive `. ## *delete user* Remove a user and all their data from the account. ```shell op delete user [flags] ``` ## *delete vault* Remove a vault. ```shell op delete vault [flags] ``` ## *edit* ### Subcommands {#edit-subcommands} - [edit connect](#edit-connect): Edit 1Password Connect servers and tokens - [edit document](#edit-document): Edit a document - [edit group](#edit-group): Edit a group's name or description - [edit item](#edit-item): Edit an item's details - [edit user](#edit-user): Edit a user's name or Travel Mode status - [edit vault](#edit-vault): Edit a vault's metadata ### Related commands {#edit-related-commands} - [add](#add): Grant access to groups or vaults ## *edit connect* ### Subcommands {#edit-connect-subcommands} - [edit connect server](#edit-connect-server): Rename a Connect server - [edit connect token](#edit-connect-token): Rename a Connect token ## *edit connect server* Rename a Connect server. ```shell op edit connect server [flags] ``` ### Options for edit connect server ``` --name name change the server's name ``` ### Related commands {#edit-connect-server-related-commands} - [list connect servers](#list-connect-servers): Get a list of 1Password Connect servers ## *edit connect token* Rename a Connect token. ```shell op edit connect token [flags] ``` ### Options for edit connect token ``` --name name change the tokens's name --server string only look for tokens for this 1Password Connect server ``` ### Related commands {#edit-connect-token-related-commands} - [list connect tokens](#list-connect-tokens): Get a list of tokens ## *edit document* Update a document. ```shell op edit document [flags] ``` ### Options for edit document ``` --filename name set the file's name --tags tags add one or more tags (comma-separated) to the item --title title set the item's title --vault vault look up document in this vault ``` ### How edit document works Replace the file contents of a Document item with the provided file or with the information on standard input (`stdin`). #### Update a file from standard input To update the file contents from standard input (`stdin`), enter a hyphen (`-`) instead of a path. You can use the `--filename` option to change the name of the file. ## *edit group* Change a group's name or description. ```shell op edit group [flags] ``` ### Options for edit group ``` --description description change the group's description --name name change the group's name ``` ## *edit item* Edit an item's details. ```shell op edit item [ ...] [flags] ``` ### Options for edit item ``` --generate-password[=recipe] give the item a randomly generated password --vault vault look for the item in this vault ``` ### How edit item works Use an assignment statement to change a field's value: ``` [
.]= ``` You can omit spaces when you specify the section or field name. You can also refer to the field by its JSON short name (`name` or `n`). ``` issuingcountry=Canada ``` The section is optional unless multiple sections have a field with the same name. ``` testingserver.address=db.local.1password.com developmentserver.address=db.dev.1password.com ``` You can't make a new custom section using an assignment statement. :::warning[caution] When providing secrets on the command line, always be wary of any other processes that might be monitoring what you’re doing. ::: #### Generate a password Use the `--generate-password` option to generate and set a random password for a Login or Password item. By default, it will create a 32-character password made up of letters, numbers, and symbols. You can customize the password with a password recipe. Specify the password length and which character types to use in a comma-separated list. Ingredients are: - `letters` for uppercase and lowercase letters - `digits` for numbers - `symbols` for special characters (`!@.-_*`) - `1`-`64` for password length ## *edit user* Change a user's name or Travel Mode status. ```shell op edit user [flags] ``` ### Options for edit user ``` --name name set the user's name --travelmode on|off turn Travel Mode on or off for the user ``` ## *edit vault* Edit the name, icon, and description of a vault. ```shell op edit vault [flags] ``` ### Options for edit vault ``` --description description change the vault's description --icon icon change the vault's icon --name name change the vault's name ``` ### How edit vault works Valid icon keywords are: - airplane - application - art-supplies - bankers-box - brown-briefcase - brown-gate - buildings - cabin - castle - circle-of-dots - coffee - color-wheel - curtained-window - document - doughnut - fence - galaxy - gears - globe - green-backpack - green-gem - handshake - heart-with-monitor - house - id-card - jet - large-ship - luggage - plant - porthole - puzzle - rainbow - record - round-door - sandals - scales - screwdriver - shop - tall-window - treasure-chest - vault-door - vehicle - wallet - wrench ### Related commands {#edit-vault-related-commands} - [list vaults](#list-vaults): Get a list of vaults - [get vault](#get-vault): Get details about a vault ## *encode* :::warning[caution] This command has been deprecated. Use the more secure --template flag with `create item` instead. It skips the need to encode the file. ::: ```shell op encode [flags] ``` ### How encode works Encode the JSON needed to create an item with `base64url` encoding. Accepts input from standard input (`stdin`). ### Examples for encode Encode a basic item template: ```shell op get template login | op encode ``` Save the encoded contents of a file to another file: ```shell cat my-new-login.json | op encode > my-new-login.encoded-json ``` ### Related commands {#encode-related-commands} - [get template](#get-template): Get an item template - [create item](#create-item): Create an item - [edit item](#edit-item): Edit an item's details ## *forget* Remove the details for a 1Password account from this device. ```shell op forget [flags] ``` ## *get* ### Subcommands {#get-subcommands} - [get account](#get-account): Get details about your account - [get document](#get-document): Download a document - [get group](#get-group): Get details about a group - [get item](#get-item): Get item details - [get template](#get-template): Get an item template - [get totp](#get-totp): Get the one-time password for an item - [get user](#get-user): Get details about a user - [get vault](#get-vault): Get details about a vault ## *get account* Get details about your account. ```shell op get account [flags] ``` ## *get document* Download a document and print the contents to standard output (`stdout`). ```shell op get document [flags] ``` ### Options for get document ``` --include-archive include items in the Archive --output path save the document to the file path instead of `stdout` --vault vault look for the document in this vault ``` ### How get document works #### Save to a file Use the `--output` option to have `op` save the document. This may be useful in some shells to preserve the file's original encoding. The `--output` option won't overwrite an existing file. The destination path must be an empty file or not exist. ### Examples for get document Save a document to a file called `secret-plans.text`: ```shell op get document "Top Secret Plan B" --output secret-plans.text ``` ## *get group* Get details about a group. ```shell op get group [flags] ``` ### How get group works #### Use standard input to specify objects If you enter a hyphen (`-`) instead of a single object for this command, 1Password CLI will read object specifiers from standard input (`stdin`). Separate each specifier with a new line. For more information about how to specify objects, run `op help`. You can also pass the command a list or array of JSON objects. 1Password CLI will get an item for any object that has a UUID key, ignoring line breaks. This is useful for passing information from one `op` command to another. ### Examples for get group Get details for all groups: ```shell op list groups | op get group - ``` Get details for the groups who have access to a vault: ```shell op list groups --vault "Production keys" | op get group - ``` ## *get item* Return details about an item. ```shell op get item [flags] ``` ### Options for get item ``` --fields fields only return data from these fields --format format return data in this format (CSV or JSON) (use with --fields) --include-archive include items in the Archive --share-link get a shareable link for the item --vault vault look for the item in this vault ``` ### How get item works By default, `get item` returns a complete 1Password JSON object. #### Customize returned data To only get details from specific fields, use the `--fields` option. Specify fields in a comma-separated list. You can omit spaces when you specify the section or field name. You can also refer to the field by its JSON short name (`name` or `n`). When you specify one field, its data is returned as a simple string. If you specify more than one field, the data is returned in a simple key-value pair JSON object. If a field doesn't exist, an empty value is returned. Use the `--format` option to change the output format to JSON or CSV. #### Specify items on standard input The command treats each line of information on standard input (`stdin`) as an object specifier. Run `op help` to learn more about how to specify objects. The input can also be a list or array of JSON objects. The command will get an item for any object that has a UUID key. This is useful for passing information from one `op` command to another. #### Items in the Archive Items in the Archive are ignored by default. To get details for an item in the Archive, specify the item by UUID or use the `--include-archive` option. ### Examples for get item Get details for all items with a specified tag: ```shell op list items --tags documentation | op get item - ``` Get a CSV list of the website, username, and password for all logins in a vault: ```shell op list items --categories Login --vault Staging | op get item - --fields website,username,password --format CSV ``` ## *get template* Return a template for an item type. ```shell op get template [flags] ``` ### How get template works You can create a new item with a template. Run `op create item --help` for more information. Categories are: - API Credential - Bank Account - Credit Card - Database - Document - Driver License - Email Account - Identity - Login - Medical Record - Membership - Outdoor License - Passport - Password - Reward Program - Secure Note - Server - Social Security Number - Software License - Wireless Router ### Related commands {#get-template-related-commands} - [encode](#encode): Encode the JSON needed to create an item - [create item](#create-item): Create an item ## *get totp* Get an item's current time-based one-time password. ```shell op get totp [flags] ``` ### Options for get totp ``` --vault vault look for the item in this vault ``` ### How get totp works #### Items in the Archive Items in the Archive are ignored by default. To get the TOTP for an item in the Archive, specify the item by UUID. ## *get user* Get details about a user. ```shell op get user [flags] ``` ### Options for get user ``` --fingerprint get the user's public key fingerprint --publickey get the user's public key ``` ### How get user works #### Use standard input to specify objects If you enter a hyphen (`-`) instead of a single object for this command, 1Password CLI will read object specifiers from standard input (`stdin`). Separate each specifier with a new line. For more information about how to specify objects, run `op help`. You can also pass the command a list or array of JSON objects. 1Password CLI will get an item for any object that has a UUID key, ignoring line breaks. This is useful for passing information from one `op` command to another. ### Examples for get user Get details for all users: ```shell op list users | op get user - ``` Get the public key for all users in a group: ```shell op list users --group "Frontend Developers" | op get user - --publickey ``` Get details for all users who have access to a vault: ```shell op list users --vault Staging | op get user - ``` ## *get vault* Get details about a vault. ```shell op get vault [flags] ``` ### How get vault works #### Use standard input to specify objects If you enter a hyphen (`-`) instead of a single object for this command, 1Password CLI will read object specifiers from standard input (`stdin`). Separate each specifier with a new line. For more information about how to specify objects, run `op help`. You can also pass the command a list or array of JSON objects. 1Password CLI will get an item for any object that has a UUID key, ignoring line breaks. This is useful for passing information from one `op` command to another. ### Examples for get vault Get details for all vaults: ```shell op list vaults | op get vault - ``` Get details for the vaults that a group has access to: ```shell op list vaults --group security | op get vault - ``` ### Related commands {#get-vault-related-commands} - [list vaults](#list-vaults): Get a list of vaults - [edit vault](#edit-vault): Edit a vault's metadata ## *list* ### Subcommands {#list-subcommands} - [list connect](#list-connect): List 1Password Connect servers and tokens - [list documents](#list-documents): Get a list of documents - [list events](#list-events): Get a list of events from the Activity Log - [list groups](#list-groups): Get a list of groups - [list items](#list-items): Get a list of items - [list templates](#list-templates): Get a list of templates - [list users](#list-users): Get the list of users - [list vaults](#list-vaults): Get a list of vaults ## *list connect* ### Subcommands {#list-connect-subcommands} - [list connect servers](#list-connect-servers): Get a list of 1Password Connect servers - [list connect tokens](#list-connect-tokens): Get a list of tokens ## *list connect servers* List 1Password Connect servers. ```shell op list connect servers [flags] ``` ### Related commands {#list-connect-servers-related-commands} - [create connect token](#create-connect-token): Issue a token for a 1Password Connect server - [edit connect server](#edit-connect-server): Rename a Connect server ## *list connect tokens* List tokens for Connect servers. ```shell op list connect tokens [flags] ``` ### Options for list connect tokens ``` --server server only list tokens for this Connect server ``` ### How list connect tokens works Returns active (`A`) and revoked (`R`) tokens. The `integrationUuid` is the UUID for the Connect server the token belongs to. ### Related commands {#list-connect-tokens-related-commands} - [edit connect token](#edit-connect-token): Rename a Connect token ## *list documents* List documents. ```shell op list documents [flags] ``` ### Options for list documents ``` --include-archive include items in the Archive --vault vault only list documents in this vault ``` ### How list documents works Returns a list of all documents the account has read access to by default. Excludes items in the Archive by default. ## *list events* List events from the Activity Log. ```shell op list events [flags] ``` ### Options for list events ``` --eventid eid start listing from event with ID eid --older list events from before the specified event ``` ### How list events works Returns the 100 most recent events by default. The Activity Log is only available for 1Password Business accounts. ### Examples for list events List events after a specific log entry: ```shell op list events --eventid 319458129 ``` List events before a specific log entry: ```shell op list events --older --eventid 319179570 ``` ## *list groups* List groups. ```shell op list groups [flags] ``` ### Options for list groups ```shell --user user list groups that a user belongs to --vault vault list groups that have direct access to a vault ``` ### How list groups works Returns all groups in an account by default. ### Examples for list groups Get details for all groups: ```shell op list groups | op get group - ``` Get details for the groups who have access to a vault: ```shell op list groups --vault Staging | op get group - ``` Get details for the groups that a person belongs to: ```shell op list groups --user wendy_appleseed@1password.com | op get group - ``` ## *list items* List items. ```shell op list items [flags] ``` ### Options for list items ``` --categories categories only list items in these categories (comma-separated) --include-archive include items in the Archive --tags tags only list items with these tags (comma-separated) --vault vault only list items in this vault ``` ### How list items works Returns a list of all items the account has read access to by default. Excludes items in the Archive by default. Categories are: - API Credential - Bank Account - Credit Card - Database - Document - Driver License - Email Account - Identity - Login - Medical Record - Membership - Outdoor License - Passport - Password - Reward Program - Secure Note - Server - Social Security Number - Software License - Wireless Router ### Examples for list items Get details for all items with a specified tag: ```shell op list items --tags documentation | op get item - ``` Get a CSV list of the `website`, `username`, and `password` for all logins in a vault: ```shell op list items --categories Login --vault Staging | op get item - --fields website,username,password --format CSV ``` ## *list templates* List available item type templates. ```shell op list templates [flags] ``` ### How list templates works Use `op get template` to get a template to use to create a new item. ### Related commands {#list-templates-related-commands} - [create item](#create-item): Create an item - [get template](#get-template): Get an item template ## *list users* List users. ```shell op list users [flags] ``` ### Options for list users ``` --group group list users who belong to a group --vault vault list users who have direct access to vault ``` ### How list users works Returns all users in an account by default. When you use the `--group` option, the output includes the user's role in the group. ### Examples for list users Get details for all users: ```shell op list users | op get user - ``` Get the public key for all users in a group: ```shell op list users --group "Frontend Developers" | op get user - --publickey ``` Get details for all users who have access to a vault: ```shell op list users --vault Staging | op get user - ``` ## *list vaults* List vaults. ```shell op list vaults [flags] ``` ### Options for list vaults ``` --group group list vaults a group has access to --user user list vaults a user has access to ``` ### How list vaults works Returns all vaults the account has access to by default. ### Examples for list vaults Get details for all vaults: ```shell op list vaults | op get vault - ``` Get details for vaults that a group has access to: ```shell op list vaults --group Security | op get vault - ``` Get details for vaults that a user has access to: ```shell op list vaults --user wendy_appleseed@1password.com | op get vault - ``` ### Related commands {#list-vaults-related-commands} - [get vault](#get-vault): Get details about a vault - [edit vault](#edit-vault): Edit a vault's metadata ## *manage* ### Subcommands {#manage-subcommands} - [manage connect](#manage-connect): Manage group access to 1Password Secrets Automation ## *manage connect* ### Subcommands {#manage-connect-subcommands} - [manage connect add](#manage-connect-add): Grant access to manage Secrets Automation - [manage connect remove](#manage-connect-remove): Revoke access to manage Secrets Automation ## *manage connect add* Grant a group access to manage Secrets Automation. ```shell op manage connect add [flags] ``` ### How manage connect add works If you don't specify a server, it adds the group to the list of Secrets Automation managers. ## *manage connect remove* Revoke access from a group to manage Secrets Automation. ```shell op manage connect remove [flags] ``` ## *reactivate* Reactivate a suspended user. ```shell op reactivate [flags] ``` ### Related commands {#reactivate-related-commands} - [suspend](#suspend): Suspend a user ## *remove* ### Subcommands {#remove-subcommands} - [remove connect](#remove-connect): Remove access to vaults from 1Password Connect servers - [remove group](#remove-group): Revoke a group's access to a vault - [remove user](#remove-user): Revoke a user's access to a vault or group ### Related commands {#remove-related-commands} - [add](#add): Grant access to groups or vaults ## *remove connect* ### Subcommands {#remove-connect-subcommands} - [remove connect server](#remove-connect-server): Revoke a Connect server's access to a vault ## *remove connect server* Revoke access to a vault from a Connect server. ```shell op remove connect server [flags] ``` ## *remove group* Revoke a group's access to a vault. ```shell op remove group [flags] ``` ## *remove user* Revoke a user's access to a vault or group. ```shell op remove user [ | ] [flags] ``` ## *signin* Sign in to a 1Password account and return a session token. ```shell op signin [ [ []]] [flags] ``` ### Options for signin ``` -l, --list list accounts set up on this device -r, --raw only return the session token --shorthand name set the short account name ``` ### How signin works #### Sign in to an account To sign in to an account the first time, use your sign-in address and email address: ```shell op signin example.1password.com wendy_appleseed@1password.com ``` After you sign in the first time, you can sign in again using only the shorthand for the account: ```shell op signin example ``` #### Use session tokens 1Password CLI uses a session token to authenticate commands with 1Password.com. Sessions expire after 30 minutes of inactivity. You can save the session token in an environment variable for 1Password CLI to use automatically or provide a token with each command using the `--session` option. To use the environment variable, run the `export` command that 1Password CLI provides after you sign in. When you run a command, 1Password CLI uses it automatically. To provide a session token each time you run a command, sign in using the `--raw` option to get a token. Then use the `--session` option with each command. #### Reuse a session token You can use the `--session` option with the `signin` command to reuse an active token or to test whether a session has expired. This may be useful when writing scripts that use 1Password CLI. If the session is active, 1Password CLI will use it and return the same token. If the session is expired, you’ll have to sign in again. #### Work with multiple accounts You can sign in to more than one account at a time. If you store the session token in an environment variable, 1Password CLI will use the account you most recently signed in to by default. Use the `--account` option to specify a different account. By default, the shorthand is your account’s subdomain. You can change it the first time you sign in by using the `--shorthand` option, or in the configuration file. Hyphens (`-`) are converted to underscores (`_`) for system compatibility. ### Examples for signin Sign in and set the environment variable in one step: ```shell eval $(op signin example) ``` ### Related commands {#signin-related-commands} - [signout](#signout): Sign out of a 1Password account ## *signout* Sign out of a 1Password account. ```shell op signout [flags] ``` ### Options for signout ``` --forget remove the details for a 1Password account from this device ``` ### How signout works Signs out of the most recently used account by default. ### Related commands {#signout-related-commands} - [signin](#signin): Sign in to a 1Password account ## *suspend* Suspend a user. ```shell op suspend [flags] ``` ### Options for suspend ``` --deauthorize-devices seconds[=0] deauthorize the user's devices after a time in seconds ``` ### Related commands {#suspend-related-commands} - [reactivate](#reactivate): Reactivate a suspended user ## *update* Check for updates to `op`. Downloads an updated version, if available. ```shell op update [flags] ``` ### Options for update ``` --directory path download the update to this path ``` --- ## Use 1Password CLI 1 :::warning[Upgrade to 1Password CLI 2] 1Password CLI 1 is deprecated as of **October 1, 2024**. Scripts and integrations that use version 1 will no longer work as expected. [Upgrade to 1Password CLI 2](/docs/cli/upgrade/) to maintain uninterrupted access and compatibility with the latest features. ::: ## Sign in or out To sign in to an account and get a session token: ```shell op signin [--raw] ``` After you sign in the first time, you can sign in again using only the shorthand for your account: ```shell op signin [--raw] ``` By default, the shorthand is your account's subdomain. You can change it the first time you sign in by using the `--shorthand` option. Hyphens (-) in a subdomain will be changed to an underscore (_). See also [*Appendix: Session management*](#appendix-session-management). ### Sign out Sessions automatically expire after 30 minutes of inactivity. You can sign out manually using the `signout` command: ```shell op signout ``` See also [*Appendix: Session management*](#appendix-session-management). ## List objects To list objects in a 1Password account: ```shell op list (users | groups | vaults | items | documents | templates) [--vault | --group ] ``` To list users or groups with access to a vault: ```shell op list (users | groups) --vault ``` To list users in a group: ```shell op list users --group ``` To list items in a vault: ```shell op list items --vault ``` To include items or documents in the Archive: ```shell op list (items | documents) [--vault ] --include-archive ``` ## List Activity Log events :::note 1Password Business The Activity Log is only available for 1Password Business accounts. ::: To list events from the [Activity Log](https://support.1password.com/activity-log): ```shell op list events [--eventid ] [--older] ``` The 100 most recent events will be listed. ### List events after a specific log entry You can provide an event ID (`eid`) as a starting point for listing entries by using the `--eventid` option. A maximum of 100 events will be returned, starting after, but not including, the provided event. ```shell op list events --eventid 319458129 ``` ### List events before a specific log entry The `--older` option can be used with the `--eventid` option to list entries that occurred before the provided event ID. ```shell op list events --older --eventid 319179570 ``` A maximum of 100 events will be returned, starting with the event before, not including, the provided event. ## Manage objects ### Get details To get details about an object: ```shell op get (account | group | vault | item | totp) [] [--vault ] [--include-archive] ``` The `--include-archive` option will allow for items in the Archive to be returned. To get the UUID of an object, look it up by name, email address, or domain. See also [*Appendix: Specifying objects*](#appendix-specifying-objects). ### Get details of an item By default, `op get item` gets details of all fields. You can get details of just the fields you want instead. For one field, 1Password CLI returns a simple string: ```shell op get item nqikpd2bdjae3lmizdajy2rf6e --fields password 5ra3jOwnUsXVjx5GL@FX2d7iZClrrQDc ``` For multiple fields, specify them in a comma-separated list. 1Password CLI returns a JSON object: ```shell op get item nqikpd2bdjae3lmizdajy2rf6e --fields username,password {"username": "wendy_appleseed", "password": "5ra3jOwnUsXVjx5GL@FX2d7iZClrrQDc"} ``` You can change the output to CSV or to always use JSON with the `--format` option. ### Create or edit an item To create an item: ```shell op create item [ ...] ``` :::important Note If you can't trust other users or processes on your system, use `op create item --template=file.json` instead. ::: To edit an item: ```shell op edit item [ ...] ``` Assignment statements follow this syntax: ``` [
.]= ``` You can omit spaces when you specify the section or field name. You can also refer to a field by its JSON short name (`name` or `n`). ``` issuingcountry=Canada ``` The section is optional unless multiple sections have a field with the same name. ``` testingserver.address=db.local.1password.com developmentserver.address=db.dev.1password.com ``` You can't make a new custom section using an assignment statement. You can generate a password for the item with the `--generate-password` option. By default, it will create a 32-character password made up of letters, numbers, and symbols. See also [*Appendix: Categories*](#appendix-categories) for a list of categories. See also [*Appendix: Specifying objects*](#appendix-specifying-objects). When you create an item, its UUID is returned. ### Delete an item To delete an item: ```shell op delete item [--vault ] ``` Use the `--archive` option to move it to the Archive instead. See also [*Appendix: Specifying objects*](#appendix-specifying-objects). ### Create or remove a vault To create a vault: ```shell op create vault [--allow-admins-to-manage ] [--description ] ``` When you create a vault, its UUID is returned. Use the `--allow-admins-to-manage` option to specify whether administrators can manage access to the vault or not. If not provided, the default policy for the account applies. To remove a vault: ```shell op delete vault ``` See also [*Appendix: Specifying objects*](#appendix-specifying-objects). ### Work with documents To create a document: ```shell op create document [--title ] [--vault <vault>] [--tags <tags>] ``` When you create a document, its UUID is returned. To download a document and save it to a file: ```shell op get document <document> [--vault <vault>] [--output <file_path>] ``` The document's contents are sent to standard output (`stdout`) by default. Use the `--output` option to save the document to a file directly. It won't overwrite an existing file unless it's empty. To delete a document: ```shell op delete document <document> [--vault <vault>] ``` Use the `--archive` option to move it to the Archive instead. See also [*Appendix: Specifying objects*](#appendix-specifying-objects). ## Manage users and groups ### Invite and confirm users To create and invite a new user: ```shell op create user <email_address> <name> ``` Users are invited by email and then must be confirmed using their email address or UUID: ```shell op confirm [<user> | --all] ``` The `--all` option confirms all users pending confirmation. ### Get user details To get details about a user: ```shell op get user <user> [--publickey | --fingerprint] ``` If the `--publickey` or `--fingerprint` options are used, only the user’s public key or public key fingerprint is returned. ### Edit users and groups To edit a user's name: ```shell op edit user <user> [--name <name>] ``` To turn Travel Mode on or off for a user: ```shell op edit user <user> --travelmode <on | off> ``` To edit the name or description of a group: ```shell op edit group <group> [--name <name>] [--description <description>] ``` ### Suspend or reactivate a user To suspend or reactivate a user: ```shell op (suspend | reactivate) <user> ``` See also [*Appendix: Specifying objects*](#appendix-specifying-objects). ### Remove a user To completely remove a user: ```shell op delete user <user> ``` See also [*Appendix: Specifying objects*](#appendix-specifying-objects). ### Manage individual access To grant a user access to a vault or group: ```shell op add user <user> [<vault> | <group>] ``` To revoke a user's access to a vault or group: ```shell op remove user <user> [<vault> | <group>] ``` See also [*Appendix: Specifying objects*](#appendix-specifying-objects). ### Manage group access To grant a group access to a vault: ```shell op add group <vault> ``` To revoke a group's access to a vault: ```shell op remove group <vault> ``` See also [*Appendix: Specifying objects*](#appendix-specifying-objects). ### Create or remove a group To create a group: ```shell op create group <name> ``` When you create a group, its UUID is returned. To remove a group: ```shell op delete group <group> ``` See also [*Appendix: Specifying objects*](#appendix-specifying-objects). ## Appendix: Checking for updates To check for updates to 1Password CLI: ```shell op update ``` If a newer version is available, 1Password CLI can download it for you. To change the download folder, use the `--directory` option. ## Appendix: Specifying objects Every object can be specified by UUID or name. Users and items can also be specified by email address and domain, respectively. | Object | UUID | Name | Emailaddress | Domain | |----------|------|------|--------------------|--------| | Group | ✅ | ✅ | — | — | | User | ✅ | ✅ | ✅ | — | | Vault | ✅ | ✅ | — | — | | Item | ✅ | ✅ | — | ✅ | | Document | ✅ | ✅ | — | — | When specifying by UUID, the item or its details will be returned, even if the item is in the Archive. You don’t need to specify `--include-archive`. ## Appendix: Categories - API Credential - Bank Account - Credit Card - Database - Document - Driver License - Email Account - Identity - Login - Membership - Outdoor License - Passport - Password - Reward Program - Secure Note - Server - Social Security Number - Software License - Wireless Router ## Appendix: Session management `op signin` will prompt you for your 1Password account password and output a command that can save your session token to an environment variable: ```shell op signin <shorthand> export OP_SESSION_<shorthand>="EXAMPLEeSHByBqEXAMPLEfdMVLLdEXAMPLEUrNMuRXQ" ``` To set the environment variable, run the `export` command manually, or use `eval` (Mac, Linux) or `Invoke-Expression` (Windows) to set it automatically. On Mac and Linux: ```shell eval $(op signin <shorthand>) ``` On Windows: ```shell Invoke-Expression $(op signin <shorthand>) ``` You can sign in to multiple accounts at the same time. ### Use with multiple accounts Commands that you run will use the account you signed in to most recently. To run a command using a specific account, use `--account <shorthand>`: ```shell op list items --account <shorthand> ``` To authenticate with a session token, sign in with the `--raw` option to get the token. Then use `--session <session_token>` with any command: ```shell op signin <shorthand> --raw ``` ```shell op list items --session <session_token> ``` ### Remove account details from your computer You can remove account details from your computer at any time. To sign out of an account and remove its details from your computer: ```shell op signout --forget ``` If you're already signed out, you can specify an account by its shorthand: ```shell op forget <shorthand> ``` ## Learn more - [1Password CLI 1: Reference](reference) --- ## About vault permissions When using scripts to [grant or revoke vault permissions](/docs/cli/grant-revoke-vault-permissions/), you must include any dependent permissions in the command. The vault permissions available to you depend on your 1Password account type. **1Password Business:** 1Password Business includes the following permissions: - **view_items**: view items in a vault. - **create_items**: create items in a vault. - **edit_items**: edit items in a vault. - **archive_items**: archive items in a vault. - **delete_items**: delete items in a vault. - **view_and_copy_passwords**: view concealed passwords and copy them to the clipboard. - **view_item_history**: view and restore previous versions of items in the vault. - **import_items**: move or copy items into the vault. - **export_items**: save items in the vault to an unencrypted file that other apps can read. - **copy_and_share_items**: copy items between vaults, or share them outside of 1Password. - **print_items**: print the contents of items in the vault - **manage_vault**: allows a team member to grant and revoke access to the vault, change permissions for others, and delete the vault. Owners will always have permission to manage vaults. 1Password Business also includes the broader permissions available in 1Password Teams: - **allow_viewing**: view items in a vault, view concealed passwords and copy them to the clipboard. - Includes the granular permissions: `view_items`, `view_and_copy_passwords`, `view_item_history`. - **allow_editing**: create, edit, move, print, copy, archive, and delete items in the vault. - Includes the granular permissions: `create_items`, `edit_items`, `archive_items`, `delete_items`, `import_items`, `export_items`, `copy_and_share_items`, `print_items`. - **allow_managing**: grant and revoke access to the vault, change permissions for others, and delete the vault. Owners will always have permission to manage vaults. - Includes the granular permission: `manage_vault`. The vault permission `move_items` is automatically added when the permissions below are all added: ``` view_items, edit_items, archive_items, view_and_copy_passwords, view_item_history, copy_and_share_items ``` In order to move an item, a user must have access to both the vault where an item is located and the destination vault. **Permission dependencies** In 1Password Business, all vault permissions have a hierarchical relationship in which narrower permissions require broader permissions to be granted alongside them. Permission dependencies are cumulative, so if a narrower permission is several levels down, it requires all of the broader permissions above it. For example, to grant the narrower permission `delete_items` you must also grant the permissions `edit_items`, `view_and_copy_passwords`, and `view_items`. Similarly, to revoke a broader permission like `view_items`, any narrower dependent permissions that have already been granted must be revoked alongside it. _[Vault permissions presented as a taxonomic tree]_ | permission | requirements | | ------------------------- | ------------------------------------------------------ | | `create_items` | `view_items` | | `view_and_copy_passwords` | `view_items` | | `edit_items` | `view_and_copy_passwords` , `view_items` | | `archive_items` | `edit_items`, `view_and_copy_passwords`, `view_items` | | `delete_items` | `edit_items`, `view_and_copy_passwords`, `view_items` | | `view_item_history` | `view_and_copy_passwords`, `view_items` | | `import_items` | `create_items`, `view_items` | | `export_items` | `view_item_history`, `view_and_copy_passwords`, `view_items` | | `copy_and_share_items` | `view_item_history`, `view_and_copy_passwords`, `view_items` | | `print_items` | `view_item_history`, `view_and_copy_passwords`, `view_items` | **1Password Teams:** 1Password Teams includes three permissions: - **allow_viewing**: view items in a vault, view concealed passwords and copy them to the clipboard. - Includes the granular permissions: `view_items`, `view_and_copy_passwords`, `view_item_history`. - **allow_editing**: create, edit, move, print, copy, archive, and delete items in the vault. - Includes the granular permissions: `create_items`, `edit_items`, `archive_items`, `delete_items`, `import_items`, `export_items`, `copy_and_share_items`, `print_items`. - **allow_managing**: grant and revoke access to the vault, change permissions for others, and delete the vault. Owners will always have permission to manage vaults. - Includes the granular permission: `manage_vault`. **Permission dependencies** | permission | requirements | | ---------------- | --------------- | | `allow_editing` | `allow_viewing` | | `allow_managing` | | To grant the permission `allow_editing`, you must also grant the broader permission `allow_viewing`. Similarly, to revoke `allow_viewing`, you must also revoke `allow_editing`. **1Password Families:** 1Password Families includes three permissions: - **allow_viewing**: view items in a vault, view concealed passwords and copy them to the clipboard. - Includes the granular permissions: `view_items`, `view_and_copy_passwords`, `view_item_history`. - **allow_editing**: create, edit, move, print, copy, archive, and delete items in the vault. - Includes the granular permissions: `create_items`, `edit_items`, `archive_items`, `delete_items`, `import_items`, `export_items`, `copy_and_share_items`, `print_items`. - **allow_managing**: grant and revoke access to the vault, change permissions for others, and delete the vault. Owners will always have permission to manage vaults. - Includes the granular permission: `manage_vault`. **Permission dependencies** | permission | requirements | | ---------------- | --------------- | | `allow_editing` | `allow_viewing` | | `allow_managing` | | To grant the permission `allow_editing`, you must also grant the broader permission `allow_viewing`. Similarly, to revoke `allow_viewing`, you must also revoke `allow_editing`. ## Learn more - [Grant and revoke vault permissions](/docs/cli/grant-revoke-vault-permissions/) - [Work with vaults](/docs/cli/reference/management-commands/vault/) --- ## Verify the authenticity of 1Password CLI To confirm the authenticity of 1Password CLI, the tool and all its updates are digitally signed and offered exclusively by 1Password. Always get updates directly from 1Password, and always [check to make sure that you have the latest version](/docs/cli/reference/update/). **Mac:** ### ZIP file To confirm that the contents of the 1Password CLI ZIP file are authentic, unzip the file, then run the following command in the unzipped folder: ```shell gpg --keyserver keyserver.ubuntu.com --receive-keys 3FEF9748469ADBE15DA7CA80AC2D62742012EA22 gpg --verify op.sig op ``` ### Package file To confirm the 1Password CLI installer file is authentic, you can verify the digital signature before installation. 1. Open the 1Password CLI installer. If you see "This package will run a program to determine if the software can be installed", select **Continue**. This will not begin the installation. 2. Select the lock icon in the top right corner of the installer window. If you don't see the lock icon, the package is unsigned, and you shouldn't install it. 3. Select **Developer ID Installer: AgileBits Inc. (2BUA8C4S2C)**. If you see a different developer ID, or the certificate doesn't have a green checkmark indicating that it's valid, don't install the package. 4. Select the triangle next to Details and scroll down. 5. Make sure that the SHA-256 fingerprint in the installer matches one of the following fingerprints. If they match, the signature is verified. Select **OK** and continue installation. _[The 1Password CLI installer window showing the developer ID and fingerprints.]_ | Hash | Fingerprint | |---------|-------------| | SHA‑256 | CA B5 78 06 1B 02 09 FB 70 93 4D A3 44 EF 6F EB CD 32 79 B1 C0 74 C5 4B 0D 7D 55 57 43 B9 D8 9F | | SHA‑256 | 14 1D D8 7B 2B 23 12 11 F1 44 08 49 79 80 07 DF 62 1D E6 EB 3D AB 98 5B C9 64 EE 97 04 C4 A1 C1 | The installer automatically verifies the files in the package. If any file has an issue, installation stops without changes to your system, and you'll see a message that the installer encountered an error. **Windows:** To confirm the 1Password CLI installer for Windows is authentic, verify that the signing certificate for `op.exe` was issued to AgileBits by Microsoft Corporation, and that the [Extended Key Usage (EKU)](https://learn.microsoft.com/en-us/azure/trusted-signing/concept-trusted-signing-cert-management#subscriber-identity-validation-eku) is correct. 1. Open PowerShell as an Administrator. 2. Verify that the certificate was issued to AgileBits: ```powershell Get-AuthenticodeSignature -FilePath .\op.exe | Select-Object -ExpandProperty SignerCertificate | Select-Object Subject #code-result open Subject ------- CN=Agilebits, O=Agilebits, L=Toronto, S=Ontario, C=CA ``` 3. Verify the certificate was issued by Microsoft Corporation: ```powershell Get-AuthenticodeSignature -FilePath .\op.exe | Select-Object -ExpandProperty SignerCertificate | Select-Object Issuer #code-result open Issuer ------ CN=Microsoft ID Verified CS AOC CA 02, O=Microsoft Corporation, C=US ``` 4. Verify the EKU matches 1Password's EKU of `1.3.6.1.4.1.311.97.661420558.769123285.207353056.500447802`: ```powershell Get-AuthenticodeSignature -FilePath .\op.exe | Select-Object -ExpandProperty SignerCertificate | Select-Object -ExpandProperty EnhancedKeyUsageList #code-result open FriendlyName ObjectId ------------ -------- 1.3.6.1.4.1.311.97.1.0 Code Signing 1.3.6.1.5.5.7.3.3 1.3.6.1.4.1.311.97.661420558.769123285.207353056.500447802 ``` --- ## Tutorial: Integrate 1Password SDKs with AI agents :::warning Security notice This article demonstrates how to use 1Password developer tools in conjunction with an agentic AI application. **It is not our recommended integration approach**. Exposing raw credentials directly to an AI model carries significant risks. Where possible, avoid passing secrets to the model. Instead, use short-lived, tightly scoped tokens, implement strong auditing practices, and minimize the model’s access to sensitive data. For more insight into our security recommendations and philosophy, please refer to our blog post: [Securing the Agentic Future](https://blog.1password.com/where-mcp-fits-and-where-it-doesnt/). ::: In this tutorial, you'll learn a workflow for providing credentials stored in 1Password to an AI agent using 1Password SDKs. We'll walk through the process using an example integration with [Anthropic Claude ](https://www.anthropic.com/claude) that automatically books a flight with your company credit card then submits an expense report in Ramp, all without hardcoding any secrets. By the end, you'll understand how to: - Follow the principle of least privilege to make sure your AI agent only has the minimum access needed to perform your task. - Create a 1Password Service Account with least privilege access to relevant items in your 1Password account. - Create secret reference URIs that point to where your credentials are stored in 1Password, so you can avoid hardcoding your secrets in plaintext. - Use the 1Password SDKs to fetch the secrets your AI agent needs at runtime. With this workflow, your AI agent can access only the secrets in 1Password it needs to authenticate into services. And you can see what items the agent accesses by creating a [service account usage report](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault). ## Prerequisites 1. [1Password subscription](https://1password.com/pricing/password-manager). 2. [1Password desktop app](https://1password.com/downloads/). (Optional) 3. Basic knowledge of AI agents. 4. Basic knowledge of Python. 5. Familiarity with 1Password SDKs. To learn how to get started, see the [end-to-end setup tutorial](/docs/sdks/setup-tutorial). ## Part 1: Set up a 1Password Service Account scoped to a vault In the first part of this tutorial, you'll learn how to use 1Password to follow the security [principle of least privilege](https://blog.1password.com/guiding-principles-how-least-privilege-leads-to-more-security/), which requires that a process only be given the minimum level of access needed to complete its task. To do this, you'll create a vault in your 1Password account that only contains the secrets your AI agent needs. Then you'll create a service account that only has read access to the new vault, and can't access any other items in your account. When your agent authenticates to 1Password using the service account, it won't have any unnecessary access or permissions beyond the bare minimum. ### Step 1: Create a vault that only contains items required for the task First, create a vault that only contains the credentials you'll need to perform the task you want the AI agent to complete. For our example, we'll create a new vault `Tutorial` that contains our Navan and Ramp logins, and our travel credit card. 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select the plus button in the sidebar next to your account name. 3. Enter `Tutorial` for the vault name, then select **Create**. 4. [Move or copy](https://support.1password.com/move-copy-items/) the items you need for the task into the vault. ### Step 2: Create a service account scoped to the vault [Service accounts](/docs/service-accounts) are a token-based authentication method that you can scope to specific vaults and permissions. For this tutorial, we'll create a service account that only has read access in the `Tutorial` vault. :::tip If you don't see the option to create service accounts, ask your administrator to [give you access to create and manage service accounts](/docs/service-accounts/manage-service-accounts#manage-who-can-create-service-accounts). ::: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/directory) in the sidebar. Or, if you already have active applications and services, select **Directory** at the top of the Developer page. 3. Under Access Tokens, select **Service Account**. 4. Give your service account a name. For example, `AI Agent Workflow Service Account`, then select **Next**. 6. On the next screen, you'll see a list of your 1Password vaults. Select the **Tutorial** vault you created in the previous step, then select the gear icon next to it. In the permissions dropdown, select **Read Items**. 7. Select **Create Account**. 8. On the next screen, select **Save in 1Password**, then save your newly-created service account token in the Tutorial vault. ## Part 2: Provide your credentials to the agent In the second part of this tutorial, you'll learn how to build an AI agent integration that fetches your credentials from 1Password at runtime. To do this, you'll use the `secrets.resolve()` method with secret reference URIs that point to where your credentials are stored in your 1Password account. When the agent runs, 1Password injects the actual secrets referenced by the URIs. This setup makes sure that your agent can only work with the credentials you explicitly provide as secret references in your non-dynamic controller code. This creates a clear boundary between your 1Password account and the AI agent, and prevents the agent from crafting its own requests to 1Password or accessing other credentials. :::tip Before you proceed Set up a project for your AI agent integration using 1Password SDKs. In the example below, we've created an integration using the Python SDK. Learn how to [get started with 1Password SDKs](/docs/sdks/setup-tutorial). ::: ### Step 1: Export your service account token Export the service account token you saved [in part one](#step-2-create-a-service-account-scoped-to-the-vault) to the `OP_SERVICE_ACCOUNT_TOKEN` environment variable. **Bash, Zsh, sh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN=<your-token> ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN <your-token> ``` **PowerShell:** ```powershell $Env:OP_SERVICE_ACCOUNT_TOKEN = <your-token> ``` ### Step 2: Define your credentials Define the credentials your AI agent will need using the `secrets.resolve()` method from the 1Password SDK. You can use placeholder secret references for now – we'll replace them with real secret references in the next step. In our example, we've defined: - Our Navan username and password. - Our travel credit card number, expiration date, and CVC. - Our Ramp username and password. ```python from browser_use import Agent from langchain_anthropic import ChatAnthropic from onepassword.client import Client async def main(): op_client = await Client.authenticate(os.getenv("OP_SERVICE_ACCOUNT_TOKEN"), "Claude Agent Demo", "v0.0.1") credentials = { "x_navan_username": await op_client.secrets.resolve("op://vault/item/field"), "x_navan_password": await op_client.secrets.resolve("op://vault/item/field"), "x_travel_credit_card_number": await op_client.secrets.resolve("op://vault/item/field"), "x_travel_credit_card_expiration": await op_client.secrets.resolve("op://vault/item/field"), "x_travel_credit_card_cvc": await op_client.secrets.resolve("op://vault/item/field"), "x_ramp_username": await op_client.secrets.resolve("op://vault/item/field"), "x_ramp_password": await op_client.secrets.resolve("op://vault/item/field") } ``` ### Step 3: Get secret references Get [secret reference URIs](/docs/cli/secret-reference-syntax) for your credentials, then paste them into your script in place of the placeholders from the previous step. 1. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 2. Turn on the [integration with 1Password CLI](/docs/cli/app-integration). 3. Open the Tutorial vault and select an item that contains a credential you want to reference in your script. 4. Select the down arrow next to the field for the secret you want to reference, then select **Copy Secret Reference**. 5. Paste the secret reference into your code in place of `op://vault/item/field`. You can also create secret references using the [1Password for VS Code extension](/docs/vscode/). Here's our example updated with secret references: ```python from browser_use import Agent from langchain_anthropic import ChatAnthropic from onepassword.client import Client async def main(): op_client = await Client.authenticate(os.getenv("OP_SERVICE_ACCOUNT_TOKEN"), "1Password Integration", "v0.0.1") credentials = { "x_navan_username": await op_client.secrets.resolve("op://Tutorial/Navan/username"), "x_navan_password": await op_client.secrets.resolve("op://Tutorial/Navan/password"), "x_travel_credit_card_number": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_number"), "x_travel_credit_card_expiration": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_expiration"), "x_travel_credit_card_cvc": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_cvc"), "x_ramp_username": await op_client.secrets.resolve("op://Tutorial/Ramp/username"), "x_ramp_password": await op_client.secrets.resolve("op://Tutorial/Ramp/password") } ``` ### Step 4: Define your agent instructions Now, provide the AI agent instructions for how to use the credentials you fetched in the previous step. In our example, we instruct the agent to book a flight using our company credit card, then file an expense report for reimbursement. :::caution AI agents can make mistakes. Make sure to double check the results of your prompts. ::: ```python from browser_use import Agent from langchain_anthropic import ChatAnthropic from onepassword.client import Client async def main(): op_client = await Client.authenticate(os.getenv("OP_SERVICE_ACCOUNT_TOKEN"), "1Password Integration", "v0.0.1") credentials = { "x_navan_username": await op_client.secrets.resolve("op://Tutorial/Navan/username"), "x_navan_password": await op_client.secrets.resolve("op://Tutorial/Navan/password"), "x_travel_credit_card_number": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_number"), "x_travel_credit_card_expiration": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_expiration"), "x_travel_credit_card_cvc": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_cvc"), "x_ramp_username": await op_client.secrets.resolve("op://Tutorial/Ramp/username"), "x_ramp_password": await op_client.secrets.resolve("op://Tutorial/Ramp/password") } agent_instructions = f""" Book a round-trip flight for a business trip to San Francisco: - Arrival: Monday, April 28, 2025, before 1:00 PM - Return: Thursday, May 1, 2025, after 11:00 AM Use Navan to find and purchase the flight. Log in using x_navan_username and x_navan_password. Use the company credit card stored as x_travel_credit_card_number, x_travel_credit_card_expiration, and x_travel_credit_card_cvc. Then open Ramp and create a new expense report for the trip. Log in using x_ramp_username and x_ramp_password. Upload the flight receipt and submit the report for reimbursement. """ llm = ChatAnthropic( model_name="claude-3-5-sonnet-20240620", temperature=0.0, timeout=100 ) agent = Agent( task=agent_instructions, llm=llm, sensitive_data=credentials, ) result = await agent.run() print(result) asyncio.run(main()) ``` Run the script, and the agent will load your secrets from 1Password and perform the defined tasks. ## Conclusion In this tutorial, you learned how to provide an AI agent with access credentials to perform a specific task, without hardcoding any secrets or giving the agent unnecessary access permissions. You can modify the provided example to work with other AI agents or language models, and extend it to support a wide range of tasks. ## Learn more - [Tutorial: Get started with 1Password SDKs](/docs/sdks/setup-tutorial) - [Load secrets using 1Password SDKs](/docs/sdks/load-secrets) - [Manage items using 1Password SDKs](/docs/sdks/manage-items) --- ## 1Password SDK concepts ## Authentication 1Password SDKs support authentication with the [1Password desktop app](#1password-desktop-app) or with a [1Password Service Account](#1password-service-account). ### 1Password desktop app You can build local integrations between 1Password and local applications or scripts that allow end users to authorize access directly on their device with prompts from their [1Password desktop app](https://1password.com/downloads/). Local authorization prompts from the 1Password desktop app allow end users to approve requests from your integration the same way they unlock the app, like with biometrics, their 1Password account password, their identity provider, or other supported methods. Prompts from 1Password clearly detail which account the integration will access, the process requesting access, and the scope and duration of that access. If the user approves, they securely grant the integration temporary access to the entirety of the authorized 1Password account. Access expires after 10 minutes of inactivity or when the user locks their account in the app. This method allows end users to use your integration with minimal setup and no token management, and enables secure, human-in-the-loop approval for sensitive workflows. _[A screenshot of a Python script running with an authorization prompt from the 1Password desktop app.]_ ### 1Password Service Account Service accounts enable you to follow the [principle of least privilege ](https://csrc.nist.gov/glossary/term/least_privilege) in your project, and automate access without human approval. Service account tokens are scoped to specific vaults and [Environments](/docs/environments), and are restricted to specific permissions in each vault. Service accounts aren't tied to an individual account, and work well in shared environments. They can't access your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vaults, and they can only manage permissions for vaults created by the service account. ### Comparison Use the following table to decide which authentication method best suits your use case. | Use case | Recommended authentication method | Why this method | | --- | --- | -- | | Quick testing and exploration | Desktop app | Desktop app authentication allows you to get started testing the SDK with your existing account credentials, no token needed. | | Minimal setup required for end users | Desktop app | New users don't need to learn about service accounts, and can get started quickly with their existing account credentials. | | Local integrations | Desktop app | Uses local authorization prompts from the 1Password desktop app. | | Human-in-the-loop approval for sensitive workflows | Desktop app | Authorization prompts from the 1Password desktop app clearly detail which account the integration will access, the process requesting access, and the scope and duration of that access. | | Full account access required | Desktop app | Desktop app authentication grants access to all the vaults you have access to, including your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vaults. | | Least-privilege access | Service account | You can scope service account tokens to only the vaults, Environments, and permissions your integration needs. | | Automate vault management | Desktop app | With desktop app authentication, you can manage any vault you have the appropriate permissions in. Service accounts can only manage permissions for vaults created by the service account. | | User-specific auditing | Desktop app | With desktop app authentication, actions can be traced to individual users for compliance and security reviews. | | Automated access | Service account | Service accounts allow you to automate access with no user present. | | Shared building | Service account | Service account tokens aren't tied to an individual user. | ## Autofill behavior ### Which credentials 1Password suggests When you create a Login or Password item, use the following IDs and field types for the credentials you want 1Password to suggest and fill: | ID | fieldType | Description | | --- | --- | --- | | `username` | `Text` | The username associated with the login. | | `password` | `Concealed` | The password associated with the login. | See [an example of how to create a Login item](/docs/sdks/manage-items#create-an-item). ### Where a login is suggested and filled The `Item` struct for Login and Password items contains an optional list of websites, so you can manage where 1Password autofills your credentials. Autofill behavior options include: | Autofill behavior | Description | | --- | --- | | `AnywhereOnWebsite` | Default. 1Password autofills credentials on any page that’s part of the website, including subdomains. | | `ExactDomain` | 1Password autofills credentials only if the domain (hostname and port) is an exact match. | | `Never` | 1Password never autofills credentials on this website. | ## Environments [1Password Environments](/docs/environments) allow you to organize and manage your project secrets as environment variables, separately from the items in your 1Password vaults. You can then [read the variables from your Environments](/docs/sdks/environments) using 1Password SDKs. ## Item categories Items in 1Password have a category that determines some characteristics about the item, like the fields available by default and whether 1Password suggests the item when you sign in to a website. Learn more about [the different types of items you can save in 1Password](https://support.1password.com/item-categories/). See [supported item categories](/docs/sdks/manage-items#item-parameters). ## Item states `ItemOverview` exposes one of two states: `Active` or `Archived`. | Item state | Description | | --- | --- | | Active | An item located inside a vault. (Default) | | Archived | An item that has been moved to the Archive. 1Password doesn’t include archived items in search results or suggest them when you fill in apps and browsers. You can keep archived items as long as you’d like. | ## Field types 1Password SDKs currently support operations on the following field types. You can only retrieve and make changes to supported field types. | Field type | Description | | --- | --- | | `Address` | An address. Specify each part of the address [in the field's details](/docs/sdks/manage-items#address). Don't set or edit the address field's value directly. | | `Concealed` | A secret value that 1Password conceals by default, like a password, API key, or credit card PIN. | | `CreditCardNumber` | A credit card number. | | `CreditCardType` | Type of credit card. For example Visa, Mastercard, or American Express. | | `Date` | A date, formatted as `YYYY-MM-DD`. | | `Email` | An email address. | | `Menu` | A menu of predefined options included in certain item types, like Database, Server, Email Account, and Wireless Router items. | | `MonthYear` | A month-year combination, formatted as `MM/YYYY`. | | `Notes` | A note about an item. | | `Phone` | A phone number. | | `Text` | A text string. | | `Totp` | A one-time password field. Must be [either a valid TOTP URL or a one-time password seed](/docs/sdks/manage-items#totp). | | `Url` | A web address to copy or open in your default web browser, not used for autofill behavior. You can [add autofill websites](#where-a-login-is-suggested-and-filled) to set where 1Password suggests and fills a Login or Password item. | | `Reference` | The [valid ID](/docs/sdks/concepts#unique-identifiers) of another item in the same vault. | | `SSHKey` | Must be a valid SSH private key – [a decrypted, PEM-encoded string](/docs/sdks/manage-items#ssh-key). SSH key fields can only be added to items with the [SSH Key](https://support.1password.com/item-categories#ssh-key) category. You can add one SSH key field per item. 1Password will generate a public key, fingerprint, and key type which are stored in the SSH key field details. | If an item contains information saved in unsupported field types, you won't be able to update or delete the item. See [supported functionality](/docs/sdks/functionality/) for more information. ## Files ### Document file A document file is a file stored in 1Password as a [Document item](https://support.1password.com/item-categories#document). You can [read, save, and replace](/docs/sdks/files/) document files saved in 1Password using the SDKs. ### Field file A field file is a file attachment saved in a 1Password item. You can [read, save, and remove](/docs/sdks/files/) file attachments saved in 1Password using the SDKs. ## Query parameters ### `otp` You can use the `otp` (or `totp`) [attribute query parameter](/docs/cli/secret-reference-syntax#attribute-parameter) to retrieve one-time passwords with the [`Resolve` function](/docs/sdks/load-secrets/). Append the `?attribute=otp` query parameter to a secret reference that points to the field where your one-time password is stored. For example: ``` op://dev/gitlab/one-time password?attribute=otp ``` ### `ssh-format` You can use the `ssh-format` [attribute query parameter](/docs/cli/secret-reference-syntax#attribute-parameter) to fetch a private SSH key in OpenSSH format using the [`Resolve` function](/docs/sdks/load-secrets/). Append the `?ssh-format=openssh` query parameter to a secret reference that points to the field where your SSH private key is stored. For example: ``` op://vault/<SSH item>/private key?ssh-format=openssh ``` ## Rate limits 1Password Service Accounts have hourly and daily rate limits. These also apply while using a service account with an SDK. Learn more about [service account rate limits](/docs/service-accounts/rate-limits). ## SDK client When you initialize an SDK, you create a 1Password SDK client instance and pass your configuration parameters to the SDK core. You can instantiate multiple SDK clients sequentially or in parallel using the same or different service account tokens. ## Secret references 1Password SDKs allow you to use [secret reference URIs](/docs/cli/secret-reference-syntax/) to avoid the risk of exposing plaintext secrets in your code. Secret references reflect changes you make in 1Password, so when you use the SDK to load a secret you get the latest value. Secret references use the following syntax: ``` op://<vault>/<item>/[section/]field[?attribute=<attribute-value>] ``` [Learn more about secret references](/docs/cli/secret-reference-syntax/). ## State management The 1Password SDK client sets up an authenticated session with the 1Password servers and automatically refreshes it whenever it expires. As a result, you don't need to worry about managing your authentication and session keys. ## Unique identifiers A unique identifier (ID) is a string of 26 numbers and letters that can be used to identify a 1Password object, like a vault, item, section, or field. IDs only change if you move an item to a different vault. 1Password SDKs require you to use IDs rather than names to refer to 1Password objects while performing item management operations. You can get IDs by [listing vaults and items](/docs/sdks/list-vaults-items/). ## Vault permissions With [1Password Business](https://1password.com/business-security) and [1Password Teams](https://1password.com/product/teams-small-business-password-manager), you can manage the permissions groups have in vaults. In 1Password Business, all vault permissions have a hierarchical relationship in which narrower permissions require broader permissions to be granted alongside them. Learn more about [1Password Business vault permissions](/docs/sdks/vault-permissions#1password-business-vault-permissions). 1Password Teams includes three broad permission levels made up of collections of the granular vault permissions available in 1Password Business. You'll need to grant or revoke all the permissions for the desired permission level. Learn more about [1Password Teams vault permissions](/docs/sdks/vault-permissions#1password-teams-vault-permissions). --- ## 1Password SDK local integration security 1Password SDKs allow you to build integrations between 1Password and other local applications and scripts that authenticate using [authorization prompts from the 1Password desktop app](/docs/sdks/concepts#1password-desktop-app) on the user's device. Authorization prompts clearly detail the process that's requesting access, which account the process will access, and the scope and duration of that access. Users must approve the request using the same method they use to unlock their 1Password app, like with biometrics or their 1Password account password. The credential used to authenticate never leaves the 1Password app process. :::tip To learn about the security model for automated access, see our [1Password Service Account security model](/docs/service-accounts/security). For information about 1Password security practices, visit the [1Password Security homepage](https://1password.com/security). ::: ## Security model Local 1Password desktop app integrations rely on a human-in-the-loop authorization model. When the integration makes a request, the 1Password desktop app prompts the user to authorize the request the same way they unlock their 1Password account in the app, like with Touch ID, Windows Hello, system authentication, or their 1Password account password. After the user grants the integration access, the SDK can then send requests to 1Password, which provides responses until access expires. Local integrations can only access 1Password after a user provides explicit authorization. To enforce this, 1Password serves the user an authorization prompt that contains the name of the 1Password account where access is requested (for example, AgileBits or Wendy Appleseed's Family) and the process requesting access, as well as the scope and duration of access that the process will receive. The user must approve the prompt for the integration to be granted access to the account. After access is granted, authorization is time-bound to ten minutes of inactivity, limited to the approved account and process, and expires if the user locks their 1Password account in the app. ## Authorization model Authorization occurs on a per-account and per-process basis. If the user is signed in to multiple accounts, each account must be authorized separately. If the user runs multiple integrations, each process must be authorized separately. Authorization expires after ten minutes of inactivity, after which the user must re-authorize. Authorization also expires if the user locks their account in the 1Password desktop app. ## Technical design ### Communication After a user turns on the option to integrate with SDKs in the 1Password desktop app, the 1Password app spawns a platform-native Inter-Process Communication (IPC) channel – Mach ports on Mac, named pipes on Windows, and Unix domain sockets on Linux – to listen for incoming connections. These channels create a direct, local connection that cannot be hijacked or redirected once established. When a new process connects to the channel through the SDKs, the 1Password desktop app prompts the user for authorization using the same method they use to unlock the app. The user must explicitly approve the prompt with biometrics, their 1Password account password, or their identity provider before any sensitive data is exchanged. ### Process identification When a process using the SDK connects to the secure communication channel, the 1Password desktop app retrieves the Process ID (PID) of the caller. The PID is used to query the operating system for the executable's name and its absolute path on the file system. Because integrations are built by third parties, the 1Password app cannot verify a 1Password-issued code signature for these binaries. Instead, the app presents the discovered app name to the user in an authorization prompt. The user acts as the final validator, which makes sure that the application requesting access is the one they intended to run. ### Authorization and session persistence Authorization is granted on a per-process basis. A single approval grants the specific process access to the authorized 1Password account for a limited duration of up to ten minutes of inactivity. If the account in the 1Password app is locked, all existing SDK authorizations are immediately revoked. ## Accepted risks - A user or application with root or administrator-level privileges on the same system may be able to circumvent one or more security measures and could obtain access to 1Password accounts. - Users of integrations must trust that the integration is not malicious. If a user knowingly installs a malicious application and grants it access to their account, the SDK will fulfill its function and provide the requested data to the application. - The SDK relies on the integrity of the local 1Password desktop application. If an attacker replaces the legitimate 1Password app with a malicious impersonator, the SDK may inadvertently transmit newly created items or secrets directly to the attacker’s application. --- ## Read 1Password Environments using 1Password SDKs # Read 1Password Environments using 1Password SDKs (Beta) You can use [1Password SDKs](/docs/sdks) to programmatically read environment variables stored in [1Password Environments (beta)](/docs/environments) and use them in your applications. ## Requirements To use this feature, you'll need to install the beta version of the Go, JS, or Python SDK: **Go:** ```shell go get github.com/1password/onepassword-sdk-go@v0.4.1-beta.1 ``` **JavaScript:** ```shell npm install @1password/sdk@0.4.1-beta.1 ``` **Python:** ```python pip install onepassword-sdk==0.4.1b1 ``` ## Read environment variables **Go:** To read environment variables stored in an Environment, use the [`GetVariables()`](https://github.com/1Password/onepassword-sdk-go/blob/beta/environments.go#L14) method. Replace `<your-environment-id>` with the [Environment's ID](#get-an-environments-id). ```go res, err := client.Environments().GetVariables(context.Background(), "<your-environment-id>") if err != nil { panic(err) } for _, env := range res.Variables { fmt.Printf("Variable %s: %s (hidden: %t)\n", env.Name, env.Value, env.Masked) } ``` The method returns a [`GetVariablesResponse`](https://github.com/1Password/onepassword-sdk-go/blob/beta/types.go#L67) struct that contains a list of the environment variables stored in the Environment. ```go // Response containing the full set of environment variables from an Environment. type GetVariablesResponse struct { // List of environment variables. Variables []EnvironmentVariable `json:"variables"` } ``` Each [`EnvironmentVariable`](https://github.com/1Password/onepassword-sdk-go/blob/beta/types.go#L32) struct in the response contains the following: - **Name**: The environment variable's name (for example, `DB_HOST`). - **Value**: The environment variable's value. - **Masked**: A boolean that indicates whether the value is hidden by default in the 1Password app. ```go // Represents an environment variable (name:value pair) and its masked state type EnvironmentVariable struct { // An environment variable's name Name string `json:"name"` // An environment variable's value Value string `json:"value"` // An environment variable's masked state Masked bool `json:"masked"` } ``` **JavaScript:** To read environment variables stored in an Environment, use the [`getVariables()`](https://github.com/1Password/onepassword-sdk-js/blob/beta/client/src/environments.ts#L11) method. Replace `<your-environment-id>` with the [Environment's ID](#get-an-environments-id). ```js const res = await client.environments.getVariables("<your-environment-id>"); for (const env of res.variables) { console.log(`Variable ${env.name}: ${env.value} (hidden: ${env.masked})`); } ``` The method returns a [`GetVariablesResponse`](https://github.com/1Password/onepassword-sdk-js/blob/beta/client/src/types.ts#L68) object that contains a list of the environment variables stored in the Environment. ```js /** Response containing the full set of environment variables from an Environment. */ interface GetVariablesResponse { /** List of environment variables. */ variables: EnvironmentVariable[]; } ``` Each [`EnvironmentVariable`](https://github.com/1Password/onepassword-sdk-js/blob/beta/client/src/types.ts#L29) object in the response contains the following: - **Name**: The environment variable's name (for example, `DB_HOST`). - **Value**: The environment variable's value. - **Masked**: A boolean that indicates whether the value is hidden by default in the 1Password app. ```js /** Represents an environment variable (name:value pair) and its masked state */ export interface EnvironmentVariable { /** An environment variable's name */ name: string; /** An environment variable's value */ value: string; /** An environment variable's masked state */ masked: boolean; } ``` **Python:** To read environment variables stored in an Environment, use the [`get_variables()`](https://github.com/1Password/onepassword-sdk-python/blob/beta/src/onepassword/environments.py#L10) method. Replace `<your-environment-id>` with the [Environment's ID](#get-an-environments-id). ```python res = await client.environments.get_variables("<your-environment-id>") for env in res.variables: print(f"Environment {env.name}: {env.value} (hidden: {env.masked})") ``` The method returns a [`GetVariablesResponse`](https://github.com/1Password/onepassword-sdk-python/blob/beta/src/onepassword/types.py#L162) object that contains a list of the environment variables stored in the Environment. ```python class GetVariablesResponse(BaseModel): """ Response containing the full set of environment variables from an Environment. """ variables: List[EnvironmentVariable] """ List of environment variables. """ ``` Each [`EnvironmentVariable`](https://github.com/1Password/onepassword-sdk-python/blob/beta/src/onepassword/types.py#L91) object in the response contains the following: - **Name**: The environment variable's name (for example, `DB_HOST`). - **Value**: The environment variable's value. - **Masked**: A boolean that indicates whether the value is hidden by default in the 1Password app. ```python class EnvironmentVariable(BaseModel): """ Represents an environment variable (name:value pair) and its masked state """ name: str """ An environment variable's name """ value: str """ An environment variable's value """ masked: bool """ An environment variable's masked state """ ``` :::note 1Password Environment variables are masked by default. To change this: 1. Open and unlock the 1Password desktop app. 2. Select **Developer** > **View Environments**. 3. Choose the Environment, select **Edit**, then select the vertical ellipsis next to the variable and select **Show value by default**. ::: ## Appendix: Get an Environment's ID To read environment variables from a 1Password Environment, you'll need its unique identifier (ID). You can find this ID in the [1Password desktop app](https://1password.com/downloads/): 1. Open and unlock the 1Password desktop app. 2. Navigate to **Developer** > **View Environments**. 3. Select **View environment** next to the Environment you want to fetch. 4. Select **Manage environment** > **Copy environment ID**. --- ## Manage files using 1Password SDKs # Manage files in 1Password using 1Password SDKs You can use 1Password SDKs to read, save, and delete files in your items in 1Password. Before you begin, [follow the steps to get started](/docs/sdks#get-started) with a 1Password SDK. > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for example code you can quickly clone and test in your project. You can store files in Password in two ways: - [**Field file**](#field-file-operations): A file attachment stored as a custom field in any item. You can attach multiple field files to each item. - [**Document file**](#document-operations): A file stored as a [Document item](https://support.1password.com/item-categories#document). Document items can only store a single document file. ## Read a file **Go:** You can read any file saved in 1Password using the [`Items().Files().Read`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L51) method with the attributes of the file you want to retrieve, and the IDs for the [item and vault](/docs/sdks/list-vaults-items/) where the file is stored. 1Password returns the file content as an array of bytes. You can get the file attributes for a file from its parent item by [retrieving it](/docs/sdks/manage-items#get-an-item). **File field:** **Document file:** **JavaScript:** You can read any file saved in 1Password using the [`items.files.read()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L68) method with the attributes of the file you want to retrieve, and the IDs for the [item and vault](/docs/sdks/list-vaults-items/) where the file is stored. 1Password returns the file content as an array of bytes. You can get the file attributes for a file from its parent item by [retrieving it](/docs/sdks/manage-items#get-an-item). **File field:** **Document file:** **Python:** You can read any file saved in 1Password using the [`items.files.read()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L37) method with the attributes of the file you want to retrieve, and the IDs for the [item and vault](/docs/sdks/list-vaults-items/) where the file is stored. 1Password returns the file content as an array of bytes. You can get the file attributes for a file from its parent item by [retrieving it](/docs/sdks/manage-items#get-an-item). **File field:** **Document file:** ## Field file operations ### Save a file You can save field files when you create an item or modify an existing item. To save a file in 1Password as a field file, you'll need to read the file locally then pass the file contents and name using the `FileCreateParams` parameter. Field file parameters include: | Parameter | Description | | --- | --- | | Name | The name of the file. | | Content | The file contents. | | Section ID | The ID for the custom section where the file will be saved. If the section the ID points to does not exist in the item, a new section will be created. | | Field ID | The ID for the field where the file will be saved. Must be unique within the `Fields` and `Files` of the item. | **Save files in a new item:** **Go:** You can add files to a new item when you [create the item](/docs/sdks/manage-items#create-an-item) by including them in the [`ItemCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L373) struct. **JavaScript:** You can add files to a new item when you [create the item](/docs/sdks/manage-items#create-an-item) by including them in the [`ItemCreateParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L304) object. **Python:** You can add files to a new item when you [create the item](/docs/sdks/manage-items#create-an-item) by including them in the [`ItemCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L553) object. **Save a file in an existing item:** **Go:** To save a file in an existing item, use the [`Items().Files().Attach()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L34) method. **JavaScript:** To save a file in an existing item, use the [`items.files.attach()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L46) method. **Python:** To save a file in an existing item, use the [`items.files.attach()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L13) method. ### Remove a file **Go:** You can delete field files using the [`Items().Files().Delete()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L69) method with the item, section, and field IDs for the file you want to delete. This will remove the file and return the modified item. **JavaScript:** You can delete field files using the [`items.files.delete()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L95) method with the item, section, and field IDs for the file you want to delete. This will remove the file and return the modified item. **Python:** You can delete field files using the [`items.files.delete()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L60) method with the item, section, and field IDs for the file you want to delete. This will remove the file and return the modified item. ## Document operations ### Save a document **Go:** To save a file in 1Password as a new Document item, read the file locally then pass the file contents to the [`Items().Create()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L63) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L24) struct. Make sure to specify `Document` as the item category. **JavaScript:** To save a file in 1Password as a new Document item, read the file locally then pass the file contents to the [`items.create()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L87) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L21) object. Make sure to specify `Document` as the item category. **Python:** To save a file in 1Password as a new Document item, read the file locally then pass the file contents to the [`items.create()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L31) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L76) object. Make sure to specify `Document` as the item category. The example below uses a `Path` object from Python's built-in `pathlib` module to specify the file path to the document on your computer. Make sure to import `Path` from `pathlib` at the top of your file. ### Replace a document **Go:** To replace the file in a Document item, read the new file locally then pass the file contents to the [`Items().Files().ReplaceDocument()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L87) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L24) struct. **JavaScript:** To replace the file in a Document item, read the new file locally then pass the file contents to the [`items.files.replaceDocument()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L122) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L21) object. **Python:** To replace the file in a Document item, read the new file locally then pass the file contents to the [`items.files.replace_document()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L85) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L76) object. The example below uses a `Path` object from Python's built-in `pathlib` module to specify the file path to the replacement document on your computer. Make sure to import `Path` from `pathlib` at the top of your file. ## Limitations 1Password SDKs currently have a maximum message size of 50 MB, which impacts the following file operations: - The SDK can't create files larger than 50 MB. - The SDK can't retrieve file contents exceeding 50 MB. - The SDK can't create items containing more than 50 MB of file content. ## Get help 1Password includes 1 GB of storage for individual accounts. Shared plans include: | Plan | Storage | | --- | --- | | 1Password Families | 1 GB per person | | 1Password Teams | 1 GB per person | | 1Password Business | 5 GB per person | If you aren't able to save documents in a 1Password Business account, ask your administrator to [turn on file storage for team members](https://support.1password.com/files/?mac#manage-who-can-save-files). ## Learn more - [Manage items using 1Password SDKs](/docs/sdks/manage-items) - [Share items using 1Password SDKs](/docs/sdks/share-items) - [List vaults and items using 1Password SDKs](/docs/sdks/list-vaults-items) - [End-to-end setup guide](/docs/sdks/setup-tutorial) --- ## Supported functionality 1Password SDKs are in active development. We're keen to hear what you'd like to see next. Let us know by upvoting or filing an issue in the [Go](https://github.com/1Password/onepassword-sdk-go/issues/new/choose) , [JavaScript](https://github.com/1Password/onepassword-sdk-js/issues/new/choose), or [Python](https://github.com/1Password/onepassword-sdk-python/issues/new/choose) SDK repo. ### Item management Operations: - [x] [Retrieve secrets](/docs/sdks/load-secrets) - [x] [Retrieve items](/docs/sdks/manage-items#get-an-item) - [x] [Create items](/docs/sdks/manage-items#create-an-item) - [x] [Update items](/docs/sdks/manage-items#update-an-item) - [x] [Delete items](/docs/sdks/manage-items#delete-an-item) - [x] [Archive items](/docs/sdks/manage-items#archive-an-item) - [x] [List items](/docs/sdks/list-vaults-items#list-items) - [x] [Add & update tags on items](/docs/sdks/manage-items#create-an-item) - [x] [Manage autofill websites and behavior](/docs/sdks/manage-items#create-an-item) - [x] [Generate passwords](/docs/sdks/manage-items#generate-a-password) - [x] [Share items](/docs/sdks/share-items/) - [x] [Manage items in bulk](/docs/sdks/manage-items#manage-items-in-bulk) Field types: - [x] API keys - [x] Passwords - [x] Concealed fields - [x] Text fields - [x] Notes - [x] SSH private keys, public keys, fingerprints, and key types - [x] One-time passwords - [x] URLs - [x] Phone numbers - [x] Credit card types - [x] Credit card numbers - [x] Emails - [x] References to other items - [x] Addresses - [x] Date - [x] MM/YY - [x] [Files attachments and Document items](/docs/sdks/files) - [x] Menus - [ ] Passkeys Learn about [supported field types](/docs/sdks/concepts#field-types). Query parameters: - [x] [`otp`](/docs/sdks/concepts#otp) - [x] [`ssh-format`](/docs/sdks/concepts#ssh-format) ### Vault management - [x] [Retrieve vaults](/docs/sdks/vaults#get-a-vault-overview) - [x] [Create vaults](/docs/sdks/vaults#create-a-vault) - [x] [Update vaults](/docs/sdks/vaults#update-a-vault) - [x] [Delete vaults](/docs/sdks/vaults#delete-a-vault) - [x] [List vaults](/docs/sdks/list-vaults-items#list-vaults) - [x] [Manage group vault permissions](/docs/sdks/vault-permissions) - [ ] Manage user vault permissions ### User & access management - [ ] Provision users - [ ] Retrieve users - [ ] List users - [ ] Suspend users - [x] [Retrieve groups](/docs/sdks/groups/) - [ ] List groups - [ ] Create groups - [ ] Update group membership ## Environments management - [x] [Read 1Password Environments](/docs/sdks/environments) (beta) ### Compliance & reporting - [ ] Watchtower insights - [ ] Travel mode - [ ] Events For now, use [1Password Events API](/docs/events-api/) directly. ### Authentication - [x] [1Password Service Accounts](/docs/service-accounts/get-started/) - [x] [User authentication](/docs/sdks/desktop-app-integrations/) - [ ] 1Password Connect For now, use the 1Password Connect SDK for [Go](https://github.com/1Password/connect-sdk-go), [JS](https://github.com/1Password/connect-sdk-js), or [Python](https://github.com/1Password/connect-sdk-python). --- ## Manage groups using 1Password SDKs If you have [1Password Business](https://1password.com/business-security) or [1Password Teams](https://1password.com/product/teams-small-business-password-manager), you can use 1Password SDKs to manage [groups](https://support.1password.com/groups/). > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for full example code you can quickly clone and test in your project. ## Get a group **Go:** To fetch a group, use the [`Groups().Get()`](https://github.com/1Password/onepassword-sdk-go/blob/main/groups.go#L14) method. Replace `groupID` with the group's [unique identifier](/docs/sdks/concepts#unique-identifiers). **JavaScript:** To fetch a group, use the [`groups.get()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/groups.ts#L11) method. Replace `groupId` with the group's [unique identifier](/docs/sdks/concepts#unique-identifiers). **Python:** To fetch a group, use the [`groups.get()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/groups.py#L18) method. Replace `group_id` with the group's [unique identifier](/docs/sdks/concepts#unique-identifiers). --- ## List vaults and items using 1Password SDKs You can use 1Password SDKs to list vaults and items in a 1Password account. This is helpful if you need to get the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) for an item or vault. Before you begin, [follow the steps to get started](/docs/sdks#get-started) with a 1Password SDK. > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for example code you can quickly clone and test in your project. ## List vaults **Go:** The [`Vaults().List()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L66) method gets all vaults in an account. **JavaScript:** The [`vaults.list()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L100) method gets all vaults in an account. **Python:** The [`vaults.list()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L49) method gets all vaults in an account. ## List items **Go:** The [`Items().List()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L181) method gets all items in a vault and can return each item's ID, title, category, state, and the ID of the vault where it's stored. It only returns active items by default. The example below returns item IDs. To list items, specify a vault ID, or pass a vault ID from the results of an item or the results of [`Vaults().List()`](#list-vaults). **JavaScript:** The [`items.list()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L70) method gets all items in a vault and can return each item's ID, title, category, state, and the ID of the vault where it's stored. It only returns active items by default. The example below returns item IDs. To list items, specify a vault ID, or pass a vault ID from the results of an item or the results of [`vaults.list()`](#list-vaults). **Python:** The [`items.list()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L188) method gets all items in a vault and can return each item's ID, title, category, state, and the ID of the vault where it's stored. It only returns active items by default. The example below returns item IDs. To list items, specify a vault ID, or pass a vault ID from the results of an item or the results of [`vaults.list()`](#list-vaults). ### Filter listed items by state You can filter listed items by their [state](/docs/sdks/concepts#item-states): `Active` or `Archived`. **Go:** To filter listed items so only archived items are returned, use the [`ItemListFilter`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1082) struct: **JavaScript:** To filter listed items so only archived items are returned, use the [`ItemListFilter`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L630) type: **Python:** To filter listed items so only archived items are returned, use the [`ItemListFilter`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1393) class: ## Learn more - [Secret reference syntax](/docs/cli/secret-reference-syntax/) - [Load secrets using 1Password SDKs](/docs/sdks/load-secrets/) - [Manage items using 1Password SDKs](/docs/sdks/manage-items/) - [Share items using 1Password SDKs](/docs/sdks/share-items/) --- ## Load secrets using 1Password SDKs You can use 1Password SDKs to securely load secrets into your code with [secret references](/docs/cli/secret-reference-syntax/). Before you begin, [follow the steps to get started](/docs/sdks#get-started) with a 1Password SDK. You can retrieve secrets from [supported field types](/docs/sdks/concepts#field-types). You can also retrieve one-time passwords using the [`otp` attribute parameter](/docs/sdks/concepts#query-parameters). A valid secret reference should use the syntax: ``` op://<vault>/<item>/[section/]<field> ``` To get a one-time password, append the `?attribute=otp` query parameter to a secret reference that points to a one-time password field in 1Password: ``` op://<vault>/<item>/[section/]one-time password?attribute=otp ``` > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for example code you can quickly clone and test in your project. ## Load a secret from 1Password Replace the placeholder [secret reference](/docs/sdks/concepts#secret-references) in the example with a secret reference URI that specifies the vault, item, section (if applicable), and field where the secret is saved in your 1Password account. If you have multiple vaults, items, or fields that share the same name, use a [unique identifier](/docs/sdks/concepts#unique-identifiers) instead of the name in the secret reference. **Go:** To retrieve a secret and print its value, use the [`Secrets().Resolve()`](https://github.com/1Password/onepassword-sdk-go/blob/main/secrets.go#L34) method. The SDK resolves the secret reference and returns the value of the 1Password field it references. You can then use this value in your code, like to authenticate to another service. **JavaScript:** To retrieve a secret and print its value, use the [`secrets.resolve()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/secrets.ts#L35) method. The SDK resolves the secret reference and returns the value of the 1Password field it references. You can then use this value in your code, like to authenticate to another service. **Python:** To retrieve a secret and print its value, use the [`secrets.resolve()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/secrets.py#L20) method. The SDK resolves the secret reference and returns the value of the 1Password field it references. You can then use this value in your code, like to authenticate to another service. ## Retrieve multiple secrets **Go:** Use the [`Secrets().ResolveAll()`](https://github.com/1Password/onepassword-sdk-go/blob/main/secrets.go#L50) method to retrieve secrets from 1Password in bulk, improving the performance of the operation. Replace the placeholder [secret references](/docs/sdks/concepts#secret-references) in the example with secret reference URIs that specify the vault, item, section (if applicable), and field where the secrets are saved in your 1Password account. **JavaScript:** Use the [`secrets.resolveAll()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/secrets.ts#L22) method to retrieve secrets from 1Password in bulk, improving the performance of the operation. Replace the placeholder [secret references](/docs/sdks/concepts#secret-references) in the example with secret reference URIs that specify the vault, item, section (if applicable), and field where the secrets are saved in your 1Password account. **Python:** Use the [`secrets.resolve_all()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/secrets.py#L39) method to retrieve secrets from 1Password in bulk, improving the performance of the operation. Replace the placeholder [secret references](/docs/sdks/concepts#secret-references) in the example with secret reference URIs that specify the vault, item, section (if applicable), and field where the secrets are saved in your 1Password account. ## Validate a secret reference **Go:** You can use the [`ValidateSecretReference()`](https://github.com/1Password/onepassword-sdk-go/blob/main/secrets.go#L66) method to make sure that your [secret reference](/docs/cli/secret-reference-syntax/) is formatted correctly. **JavaScript:** You can use the [`validateSecretReference()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/secrets.ts#L79) method to make sure that your [secret reference](/docs/cli/secret-reference-syntax/) is formatted correctly. **Python:** You can use the [`validate_secret_reference()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/secrets.py#L59) method to make sure that your [secret reference](/docs/cli/secret-reference-syntax/) is formatted correctly. If the secret reference is formatted incorrectly, the SDK will return an error that describes the syntax problem. Learn more about [secret references](/docs/cli/secret-reference-syntax). ## Learn more - [Secret reference syntax](/docs/cli/secret-reference-syntax/) - [Manage items using 1Password SDKs](/docs/sdks/manage-items/) - [List vaults and items using 1Password SDKs](/docs/sdks/list-vaults-items/) - [Share items using 1Password SDKs](/docs/sdks/share-items/) --- ## Manage items using 1Password SDKs You can use 1Password SDKs to read, write, and update secret values stored in your 1Password items. Before you begin, [follow the steps to get started](/docs/sdks#get-started) with a 1Password SDK. When managing items, you must use [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) in place of vault, item, section, and field names. You can get IDs by [listing vaults and items](/docs/sdks/list-vaults-items/). You can perform item management operations on [supported field types](/docs/sdks/concepts#field-types). Some field types have [special constraints](#appendix-field-type-constraints). > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for example code you can quickly clone and test in your project. ## Create an item **Go:** To create a new item, specify the parameters for the item and pass the defined item to the [`Items().Create()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L63) method. The following example creates a Login item with a username, password, one-time password, and a website where 1Password will autofill the credentials. The value of the one-time password field can be either a one-time password secret or an [`otpauth://` URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format). In this example, the one-time password field is organized beneath a custom section. **JavaScript:** To create a new item, specify the parameters for the item and pass the defined item to the [`items.create()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L87) method. The following example creates a Login item with a username, password, one-time password, and a website where 1Password will autofill the credentials. The value of the one-time password field can be either a one-time password secret or an [`otpauth://` URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format). In this example, the one-time password field is organized beneath a custom section. **Python:** To create a new item, specify the parameters for the item and pass the defined item to the [`items.create()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L31) method. The following example creates a Login item with a username, password, one-time password, and a website where 1Password will autofill the credentials. The value of the one-time password field can be either a one-time password secret or an [`otpauth://` URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format). In this example, the one-time password field is organized beneath a custom section. ### Item parameters Item parameters include: | Parameter | Definition | | --- | --- | | `Title` | The name of the item. | | `Category` | The [type of item](https://support.1password.com/item-categories/) you want to create. **Supported categories** `Login`, `SecureNote`, `CreditCard`, `CryptoWallet`, `Identity`, `Password`, `Document`, `ApiCredentials`, `BankAccount`, `Database`, `DriverLicense`, `Email`, `MedicalRecord`, `Membership`, `OutdoorLicense`, `Passport`, `Rewards`, `Router`, `Server`, `SshKey`, `SocialSecurityNumber`, `SoftwareLicense`, `Person` | | `Vault ID` | The ID of the vault where you want to create the item. | | `Fields` | The item fields. | | `Sections` | The item sections. | | `Notes` | The item notes. | | `Tags` | A list of tags to add to the item. | | `Websites` | An optional list of websites where 1Password will suggest and fill the login. Only available for Login and Password items. | A section organizes fields in an item under a section title. Section parameters include: | Parameter | Description | | --- | --- | | `Section ID` | A unique identifier for the section. | | `Section Title` | The name of the section. | Field parameters include: | Parameter | Description | | --- | --- | | `ID` | A unique identifier for the field. For fields that are specific to an item category, like `username` and `password` for a Login item, use the appropriate [built-in field](/docs/cli/item-fields#built-in-fields) ids. | | `Title` | The name of the field. | | `Field type` | The [type of field](/docs/sdks/concepts#field-types). Some field types have [special constraints](#appendix-field-type-constraints).**Supported fields** `Address`, `Concealed`, `CreditCardNumber`, `CreditCardType`, `Date`, `Email`, `Menu`, `MonthYear`, `Notes`, `Phone`, `Reference`, `Text`, `Totp`, `Url`, `SSHKey` | | `Value` | The value stored in the field. | | `Field Details` | Optional for most field types. Required for [Address fields](#address). | | `Section ID` | Organizes a field under a section. Required for all fields except built-in fields like `username` and `password`. If you create a custom field without a section, 1Password will create an empty section and assign the field to it. | Autofill website parameters include: | Parameter | Description | | --- | -- | | URL | The URL for the website. | | Label | The name of the website. | | Autofill behavior | When 1Password will autofill your credentials on the website. Options include:`AnywhereOnWebsite`: 1Password autofills credentials on any page that’s part of the website, including subdomains. `ExactMatch`: 1Password autofills credentials only if the domain (hostname and port) is an exact match.`Never`: 1Password never autofills credentials on this website. | :::tip To manage items that include files, [learn how to manage files using 1Password SDKs](/docs/sdks/files/). ::: ## Get an item **Go:** To get an item, pass the item ID and vault ID for the item to the [`Items().Get()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L96) method. To get the item [created in the first step](#create-an-item): **JavaScript:** To get an item, pass the item ID and vault ID for the item to the [`items.get()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L37) method. To get the item [created in the first step](#create-an-item): **Python:** To get an item, pass the item ID and vault ID for the item to the [`items.get()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L74) method. To get the item [created in the first step](#create-an-item): ## Get a one-time password You can use 1Password SDKs to get the value stored in a field, like the six-digit one-time password code from a `Totp` field. **Go:** To retrieve and print a one-time password from the item [created in the first step](#create-an-item): **JavaScript:** To retrieve and print a one-time password from the item [created in the first step](#create-an-item): **Python:** To retrieve and print a one-time password from the item [created in the first step](#create-an-item): ## Update an item **Go:** To update an item, [fetch the item](#get-an-item) you want to update, specify the changes you want to make, then pass the updated item to the [`Items().Put()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L130) method. **JavaScript:** To update an item, [fetch the item](#get-an-item) you want to update, specify the changes you want to make, then pass the updated item to the [`items.put()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L47) method. **Python:** To update an item, [fetch the item](#get-an-item) you want to update, specify the changes you want to make, then pass the updated item to the [`items.put()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L112) method. ## Archive an item **Go:** To archive an item, pass the item ID and vault ID for the item to the [`Items().Archive()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L172) method. **JavaScript:** To archive an item, pass the item ID and vault ID for the item to the [`items.archive()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L65) method. **Python:** To archive an item, pass the item ID and vault ID for the item to the [`items.archive()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L170) method. ## Delete an item **Go:** To delete an item, pass the item ID and vault ID for the item to the [`Items().Delete()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L146) method. **JavaScript:** To delete an item, pass the item ID and vault ID for the item to the [`items.delete()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L52) method. **Python:** To delete an item, pass the item ID and vault ID for the item to the [`items.delete()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L131) method. ## Generate a password **Go:** You can use the [`Secrets.GeneratePassword()`](https://github.com/1Password/onepassword-sdk-go/blob/main/secrets.go#L89) method to generate a password by passing a [`PIN`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1155), [`Random`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1161), or [`Memorable`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1143) password recipe struct, depending on the type of password you want to generate. **PIN:** Generates a PIN code. You can specify the length of the generated code. **Random:** Generates a random password. You can choose: - Whether the password includes digits. - Whether the password includes symbols. - The length of the password. **Memorable:** Generates a memorable password. For example, `correct-horse-battery-staple`. You can choose: - The separator used between words. Options: `Spaces`, `Hyphens`, `Underscores`, `Periods`, `Commas` - Whether the memorable password is made up of full words or random syllables. Options: `FullWords`, `Syllables`, `ThreeLetters` - Whether to capitalize one section of the generated password. - The number of words included in the password. **JavaScript:** You can use the [`Secrets.generatePassword()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/secrets.ts#L97) method to generate a password by passing a [`PIN`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L653), [`Random`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L660), or [`Memorable`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L640) password recipe object, depending on the type of password you want to generate. **PIN:** Generates a PIN code. You can specify the length of the generated code. **Random:** Generates a random password. You can choose: - Whether the password includes digits. - Whether the password includes symbols. - The length of the password. **Memorable:** Generates a memorable password. For example, `correct-horse-battery-staple`. You can choose: - The separator used between words. Options: `Spaces`, `Hyphens`, `Underscores`, `Periods`, `Commas` - Whether the memorable password is made up of full words or random syllables. Options: `FullWords`, `Syllables`, `ThreeLetters` - Whether to capitalize one section of the generated password. - The number of words included in the password. **Python:** You can use the [`Secrets.generate_password()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/secrets.py#L77) method to generate a password by passing a [`PIN`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1439), [`Random`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1450), or [`Memorable`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1414) password recipe object, depending on the type of password you want to generate. **PIN:** Generates a PIN code. You can specify the length of the generated code. **Random:** Generates a random password. You can choose: - Whether the password includes digits. - Whether the password includes symbols. - The length of the password. **Memorable:** Generates a memorable password. For example, `correct-horse-battery-staple`. You can choose: - The separator used between words. Options: `Spaces`, `Hyphens`, `Underscores`, `Periods`, `Commas` - Whether the memorable password is made up of full words or random syllables. Options: `FullWords`, `Syllables`, `ThreeLetters` - Whether to capitalize one section of the generated password. - The number of words included in the password. ## Manage items in bulk ### Create items **Go:** You can use the [`Items().CreateAll()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L79) method to batch create up to 100 items within a single vault. Learn more about [field type constraints](#appendix-field-type-constraints). The following example creates three example items in the vault specified with the `vaultId` variable. Make sure to set this variable to the [unique identifier](/docs/sdks/concepts#unique-identifiers) for the vault where you want to create the items. **JavaScript:** You can use the [`items.createAll()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L108) method to batch create up to 100 items within a single vault. Learn more about [field type constraints](#appendix-field-type-constraints). The following example creates three example items in the vault specified with the `vault.id` variable. Make sure to set this variable to the [unique identifier](/docs/sdks/concepts#unique-identifiers) for the vault where you want to create the items. **Python:** You can use the [`items.create_all()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L52) method to batch create up to 100 items within a single vault. Learn more about [field type constraints](#appendix-field-type-constraints). The following example creates three example items in the vault specified with the `vault.id` variable. Make sure to set this variable to the [unique identifier](/docs/sdks/concepts#unique-identifiers) for the vault where you want to create the items. ### Get items **Go:** You can use the [`Items().GetAll()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L113) method to fetch up to 50 items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). To get the items you [created in the previous step](#create-items-): **JavaScript:** You can use the [`items.getAll()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L155) method to fetch up to 50 items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). To get the items you [created in the previous step](#create-items-): **Python:** You can use the [`items.get_all()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L93) method to fetch up to 50 items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). To get the items you [created in the previous step](#create-items-): ### Delete items **Go:** You can use the [`Items().DeleteAll()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L155) method to batch delete a list of items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). Deleted items [remain available in Recently Deleted](https://support.1password.com/archive-delete-items/) for 30 days. To delete the items you [created in the previous step](#create-items-): **JavaScript:** You can use the [`items.deleteAll()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L57) method to batch delete a list of items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). Deleted items [remain available in Recently Deleted](https://support.1password.com/archive-delete-items/) for 30 days. To delete the items you [created in the previous step](#create-items-): **Python:** You can use the [`items.delete_all()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L151) method to batch delete a list of items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). Deleted items [remain available in Recently Deleted](https://support.1password.com/archive-delete-items/) for 30 days. To delete the items you [created in the previous step](#create-items-): ## Appendix: Field type constraints Some [supported field types](/docs/sdks/concepts#field-types) have special requirements and constraints. ### Address For an `Address` type item field, the address field's value is built using the address field's details, because address string formats can differ according to the country. You must define which piece of the address each particular string corresponds to so that 1Password can properly create the address string. To change the value of an `Address` field, edit the item field details directly, not the field value. **Go:** **JavaScript:** **Python:** ### Date For a `Date` type item field, the date field's value must be a string formatted as `YYYY-MM-DD`. For example, `1998-03-15`. **Go:** **JavaScript:** **Python:** ### MonthYear For a `MonthYear` type item field, the value must be a string formatted as `MM/YYYY`. For example, `10/2000`. **Go:** **JavaScript:** **Python:** ### Reference For a `Reference` type item field, the reference field's value must be the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of another item that exists within the same vault. This ID should be a 26 character alphanumeric string. For example, `vhn2qfnmizg6rw4iqottczq3fy`. **Go:** **JavaScript:** **Python:** ### SSH Key For an `SSHKey` type item field, the SSH key field's value must be a valid SSH private key – a decrypted, PEM-encoded string. You can use private key strings generated from the source of your choice, or you can generate SSH keys in your SDK language using that language's native support. Currently, if you attempt to pass an encrypted private key, you'll see an error. SSH key fields can only be added to items with the [SSH Key](https://support.1password.com/item-categories#ssh-key) category. You can add one SSH key field per item. When you create an item with an SSH key field assigned to it, 1Password will generate a public key, fingerprint, and key type which are stored in the SSH key field details. **Go:** The following example shows how to generate a valid SSH private key in Go and adds it to a new SSH Key item in 1Password. **JavaScript:** The following example shows how to generate a valid SSH private key in JavaScript and adds it to a new SSH Key item in 1Password. **Python:** The following example shows how to generate a valid SSH private key in Python and adds it to a new SSH Key item in 1Password. ### TOTP For a `Totp` type item field, the TOTP field's value must either be a valid one-time password URL (for example, `otpauth://totp/rsnjfceadiejs?secret=e4dw4xrdq34wd3qw3&issuer=vfsrfesfes`), or a one-time password seed (for example, `e4dw4xrdq34wd3qw3`). **Go:** **JavaScript:** **Python:** ## Troubleshooting If you aren't able to create, edit, or delete items and see an error that you "don't have the right permissions to execute this argument," check your service account's permissions in the vault where the items are saved: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Choose the service account, then confirm that you see `Read & Write` next to the vault in the Vaults table. If your service account only has read access, you'll need to [create a new service account](/docs/service-accounts/get-started#create-a-service-account) with read and write permissions. _[1Password.com open to the details of a service account.]_ ## Learn more - [Secret reference syntax](/docs/cli/secret-reference-syntax/) - [Load secrets using 1Password SDKs](/docs/sdks/load-secrets/) - [Manage files using 1Password SDKs](/docs/sdks/files/) - [Share items using 1Password SDKs](/docs/sdks/share-items/) - [List vaults and items using 1Password SDKs](/docs/sdks/list-vaults-items/) --- ## 1Password SDKs 1Password SDKs allow you to build integrations that programmatically interact with 1Password using Go, JavaScript, or Python. With 1Password SDKs, you can: - **Secure your applications**: Load secrets into your code with [secret references](/docs/sdks/load-secrets) or read [environment variables](/docs/sdks/environments/) from 1Password Environments. - **Automate item management**: Programmatically [manage items](/docs/sdks/manage-items) in your 1Password account. - **Securely share items**: [Share items](/docs/sdks/share-items) with anyone, whether or not they have a 1Password account. - **Manage vaults and access**: [Manage your team's vaults](/docs/sdks/vaults) and the [permissions groups have](/docs/sdks/vault-permissions) in them. - **Support biometric authorization**: Build local integrations that users authorize with prompts from the [1Password desktop app](/docs/sdks/concepts#1password-desktop-app) for human-in-the-loop approval and minimal setup for end users. - **Support automated access**: Build integrations that authenticate with [service account tokens](/docs/sdks/concepts#1password-service-account) for least-privilege access and automated environments. See a full list of [supported functionality](/docs/sdks/functionality). ## Supported languages ## Example integrations See examples of how our partners have used SDKs to build integrations with 1Password: - ****: Securely load API keys and other secrets stored in 1Password into Postman without exposing any secrets in plaintext. Learn more - ****: Dynamically import secrets from 1Password into your environment. The provider will return a map of names to Secrets. Learn more ## About the current version 1Password SDKs are currently in version 0, which means they can meet the stability and scalability requirements of production use cases. During version 0, expect more frequent releases as we add additional features and languages. - There is a possibility of breaking changes when you upgrade from one version 0 release to another, for example 0.1.X to 0.2.0. Minor releases (0.1.X to 0.1.Y) will not include breaking changes. - Integration authors may need to update their code when updating the SDK version. Existing code and integrations won’t be affected, as these will have the SDK pinned at a specific version via package.json (JS), requirements.txt (Python), or go.mod (Go). - We will provide three months of support and security patches for version 0, so you can upgrade when it makes sense for your workflows and teams. You can find information about the latest releases in the [1Password SDK release notes](https://releases.1password.com/developers/sdks/). ## Get started Before you get started, you'll need to [sign up for a 1Password account](https://1password.com/pricing/password-manager). ### Step 1: Decide how you want to authenticate You can choose between two [authentication methods](/docs/sdks/concepts#authentication) for 1Password SDKs: local authorization prompts from the [1Password desktop app](/docs/sdks/concepts#1password-desktop-app) or automated authentication with a [1Password Service Account](/docs/sdks/concepts#1password-service-account). - **1Password desktop app**: Best for integrations that run locally on a user's machine. Use desktop app authentication if you want minimal setup for end users, human-in-the-loop approval for sensitive workflows, user-specific auditing, if you need access to your full account, or if you need to perform vault management operations. - **Service account**: Best for automated access. Use a service account if you want a token-based authentication method that isn't associated with an individual account to automate access, limit your integration to least privilege access, or for shared building. Service accounts can't access your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault. **1Password desktop app:** 1. Install 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 2. Sign in to the account you want to use with your integration. 3. Select your account or collection at the top of the sidebar, then navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 4. Under Integrate with the 1Password SDKs, select **Integrate with other apps**. 5. If you want to authenticate with biometrics, navigate to **Settings** > **[Security](onepassword://settings/security)**, then turn on the option to unlock using [Touch ID](https://support.1password.com/touch-id-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or [system authentication](https://support.1password.com/system-authentication-linux/). _[The Integrate with other apps setting]_ **Service account:** Create a service account Create a [1Password Service Account](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/?source=dev-portal) and give it access to the vaults and [Environments](/docs/environments) you want your integration to be able to access. To allow your integration to update items, make sure to give the service account **both read and write permissions** in the appropriate vaults. To allow your integration to share items, also add the **share permission**. Provision your service account token We recommend provisioning your token from the environment. Use the following example to provision your token to an environment variable named `OP_SERVICE_ACCOUNT_TOKEN`. You can also provision your token in other ways, like by reading it from a file. **bash, sh, zsh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token> ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN <your-service-account-token> ``` **Powershell:** ```shell $Env:OP_SERVICE_ACCOUNT_TOKEN = "<your-service-account-token>" ``` ### Step 2: Install the SDK Install the SDK in your project. **Go:** ```go go get github.com/1password/onepassword-sdk-go ``` **JavaScript:** ```shell npm install @1password/sdk ``` **Python:** ```python pip install onepassword-sdk ``` ### Step 3: Import the SDK Import the SDK into your project. **Go:** **JavaScript:** CommonJS ES Modules **Python:** ### Step 4: Initialize the SDK When you initialize the SDK, you create a client instance that contains your configuration parameters. For desktop app integrations, you'll need to provide your 1Password account name. For service account authentication, you'll need to provide your service account token. **1Password desktop app:** Replace your-account-name in the code below with your 1Password account name as it appears at the top of the left sidebar in the 1Password app. You can use the account ID that [1Password CLI](/docs/cli/get-started) returns with [`op account list --format json`](/docs/cli/reference/management-commands/account#account-list). Use the value in the `account_uuid` field. Make sure to specify a name and version for your application in place of `My 1Password Integration` and `v1.0.0`. _[The Integrate with other apps setting]_ **Go:** :::note This example prints an error message and exits if initialization fails. Because it writes the error to standard error, it uses Go’s `os` package, which you’ll need to import in your project. See the [complete example in Step 5](#step-5-start-building) for more context. ::: ```go [{ "color": "sunbeam", "lineNo": 4, "substr": "your-account-name" }] // Connects to the 1Password desktop app. client, err := onepassword.NewClient(context.Background(), // TODO: Set to your 1Password account name. onepassword.WithDesktopAppIntegration("your-account-name"), // TODO: Set to your own integration name and version. onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), ) if err != nil { fmt.Fprintln(os.Stderr, "Initialization error:", err) os.Exit(1) } ``` **JavaScript:** :::note The 1Password JavaScript SDK is asynchronous and returns Promises. To make sure your code waits for 1Password to respond before moving to the next line, we recommend using the `await` keyword inside an `async` function. See the [complete example in Step 5](#step-5-start-building) for the full structure. ::: ```js [{ "color": "sunbeam", "lineNo": 4, "substr": "your-account-name" }] // Connects to the 1Password desktop app. const client = await sdk.createClient({ // TODO: Set to your 1Password account name. auth: new sdk.DesktopAuth("your-account-name"), // TODO: Set to your own integration name and version. integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); ``` **Python:** :::note The Python SDK is asynchronous. To wait for a response from 1Password, use the `await` keyword inside an `async` function in your code. See the [complete example in Step 5](#step-5-start-building) for the full structure. ::: ```python [{ "color": "sunbeam", "lineNo": 5, "substr": "your-account-name" }] # Connects to the 1Password desktop app. client = await Client.authenticate( auth=DesktopAuth( # TODO: Set to your 1Password account name. account_name="your-account-name" ), # TODO: Set to your own integration name and version. integration_name="My 1Password Integration", integration_version="v1.0.0", ) ``` **Service account:** In the following example, the SDK gets the service account token string from the `OP_SERVICE_ACCOUNT_TOKEN` environment variable. Make sure to specify a name and version for your application in place of `My 1Password Integration` and `v1.0.0`. **Go:** **JavaScript:** **Python:** ### Step 5: Start building You can test your setup by building a simple integration that lists all the titles of all the vaults you or the service account has access to. **1Password desktop app:** **Go:** ```go title="main.go" package main "context" "fmt" "os" "github.com/1password/onepassword-sdk-go" ) func main() { // Connects to the 1Password desktop app. client, err := onepassword.NewClient(context.Background(), // TODO: Set to your 1Password account name. onepassword.WithDesktopAppIntegration("your-account-name"), // TODO: Set to your own integration name and version. onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), ) if err != nil { fmt.Fprintln(os.Stderr, "Initialization error:", err) os.Exit(1) } // Lists vault titles vaults, err := client.Vaults().List(context.Background()) if err != nil { panic(err) } for _, vault := range vaults { fmt.Println(vault.Title) } } ``` ```shell go run main.go #code-result Development Production Private ``` **JavaScript:** ```js title="example.js" async function main() { // Connects to the 1Password desktop app. const client = await sdk.createClient({ // TODO: Set to your 1Password account name. auth: new sdk.DesktopAuth("your-account-name"), // TODO: Set to your own integration name and version. integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); // Lists vault titles const vaults = await client.vaults.list({ decryptDetails: true }); for (const vault of vaults) { console.log(vault.title); } } main(); ``` ```shell node index.js #code-result Development Production Private ``` **Python:** ```python title="example.py" from onepassword import Client, DesktopAuth async def main(): # Connects to the 1Password desktop app. client = await Client.authenticate( auth=DesktopAuth( # TODO: Set to your 1Password account name. account_name="your-account-name" ), # TODO: Set to your own integration name and version. integration_name="My 1Password Integration", integration_version="v1.0.0", ) # Lists vault titles vaults = await client.vaults.list() for vault in vaults: print(vault.title) if __name__ == "__main__": asyncio.run(main()) ``` ``` python3 example.py #code-result Development Production Private ``` **Service account:** In the following example, the service account is scoped to a vault titled `Development`. **Go:** ```go title="main.go" package main "context" "fmt" "os" "github.com/1password/onepassword-sdk-go" ) func main() { // Gets your service account token from the environment. token := os.Getenv("OP_SERVICE_ACCOUNT_TOKEN") client, err := onepassword.NewClient(context.Background(), onepassword.WithServiceAccountToken(token), // TODO: Set to your own integration name and version. onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), ) if err != nil { fmt.Fprintln(os.Stderr, "Initialization error:", err) os.Exit(1) } // Lists vault titles vaults, err := client.Vaults().List(context.Background()) if err != nil { panic(err) } for _, vault := range vaults { fmt.Println(vault.Title) } } ``` ```shell go run main.go #code-result Development ``` **JavaScript:** ```js title="index.js" async function main() { const client = await sdk.createClient({ // Gets your service account token from the environment. auth: process.env.OP_SERVICE_ACCOUNT_TOKEN, // TODO: Set to your own integration name and version. integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); // Lists vault titles const vaults = await client.vaults.list({ decryptDetails: true }); for (const vault of vaults) { console.log(vault.title); } } main(); ``` ```shell node index.js #code-result Development ``` **Python:** ```python title="example.py" from onepassword import Client async def main(): # Gets your service account token from the environment. token = os.getenv("OP_SERVICE_ACCOUNT_TOKEN") client = await Client.authenticate( auth=token, # TODO: Set to your own integration name and version. integration_name="My 1Password Integration", integration_version="v1.0.0", ) # Lists vault titles vaults = await client.vaults.list() for vault in vaults: print(vault.title) if __name__ == "__main__": asyncio.run(main()) ``` ```shell python3 example.py #code-result Development ``` Visit the [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/blob/main/example/example.py) SDK GitHub repositories for more examples. ## Get help To get help with 1Password SDKs, join our [Developer Slack workspace](https://developer.1password.com/joinslack) and ask a question in the `#sdk` channel. To request a new feature or report a bug, file an issue in the appropriate GitHub repo: - [Go](https://github.com/1Password/onepassword-sdk-go/issues/new/choose) - [JavaScript](https://github.com/1Password/onepassword-sdk-js/issues/new/choose) - [Python](https://github.com/1Password/onepassword-sdk-python/issues/new/choose) --- ## Tutorial: Get started with 1Password SDKs and 1Password Service Accounts In this tutorial, you'll build a simple JavaScript application that securely fetches a secret from your 1Password account. In the process, you'll learn how to: - Create a new test vault in your 1Password account. - Create a service account that can only access the test vault. - Save a secret in the test vault. - Set up your project, and install and configure the 1Password JS SDK. - Get a secret reference URI that points to the test secret you created. - Build a simple application that takes the secret reference as input and outputs the actual secret. :::tip This tutorial covers end-to-end setup for the [1Password JavaScript SDK](https://github.com/1Password/onepassword-sdk-js?tab=readme-ov-file#-get-started). Learn more about the [1Password Go SDK](https://github.com/1Password/onepassword-sdk-go?tab=readme-ov-file#-get-started) and the [1Password Python SDK](https://github.com/1Password/onepassword-sdk-python?tab=readme-ov-file#requirements). ::: ## Prerequisites 1. [1Password subscription](https://1password.com/pricing/password-manager). 2. (Optional) [1Password desktop app](https://1password.com/downloads/). 3. Basic knowledge of JavaScript. ## Part 1: Set up a 1Password Service Account In the first part of the tutorial, you'll create a vault and item in your 1Password account to use for testing, and set up a service account to authenticate the SDK. ### Step 1: Create a new vault First, create a new vault named Tutorial. You'll scope your service account to this vault, so it can only access the test item you create for this tutorial. 1. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 2. Select the plus icon in the sidebar next to your account name. 3. Enter `Tutorial` for the vault name, then select **Create**. _[]_ ### Step 2: Create a service account Next, create a [1Password Service Account](/docs/service-accounts/get-started/). This is a token-based authentication method that you can scope to specific vaults and permissions, so your process only has the minimum required access to your account. 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/directory) in the sidebar. Or, if you already have active applications and services, select **Directory** at the top of the Developer page. 3. Under Access Tokens, select **Service Account**. If you don't see the option to create service accounts, ask your administrator to [give you access to create and manage service accounts](/docs/service-accounts/manage-service-accounts#manage-who-can-create-service-accounts). 4. Give your service account a name. For this tutorial, use `Temp Service Account`. _[]_ 5. Select **Next**. 6. On the next screen, you'll see a list of your 1Password vaults. Select the **Tutorial** vault you created in the previous step, then select the gear icon next to it. In the permissions dropdown, check **Read Items** and **Write Items**. _[]_ 7. Select **Create Account**. 8. On the next screen, select **Save in 1Password**, then save your newly-created service account token in the Tutorial vault. _[]_ ### Step 3: Create a secret to retrieve with the SDK Next, create an example API credential item in the Tutorial vault. In the second half of the tutorial, you'll build a simple application to fetch the credential secret from this item. 1. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 2. Select **+ New Item** to create a new item. 3. Select **API credential** for the item category. 4. For the purpose of this tutorial, enter `tutorial` for the username and `example credential` for the credential. 5. Select the Tutorial vault you created in step 1 from the dropdown next to the Save icon. 6. Select **Save** to create the item. You should now see the API credential item in your Tutorial vault. _[]_ ## Part 2: Install and configure a 1Password SDK In this part of the tutorial, you'll create a new folder for your project, set up a NodeJS runtime environment in it, then install and configure the 1Password JavaScript SDK. ### Step 1: Set up a NodeJS runtime environment Create a new folder for your project, then make sure you have NodeJS installed. 1. Open your terminal and create a new folder named Tutorial: ```shell mkdir Tutorial ``` 2. Change directories to the Tutorial folder, then check to make sure you have NodeJS version 18 or later installed: ```shell cd Tutorial && node -v #code-result v20.16.8 ``` If you don't see an existing NodeJS version, or if you have an earlier version installed, [learn how to install the latest version of NodeJS](https://nodejs.org/). Then, initialize a NodeJS project in your Tutorial folder: ```shell npm init -y #code-result Wrote to /Users/wendy.appleseed/Tutorial/package.json: { "name": "Tutorial", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" } ``` ### Step 2: Add support for Modules After you've initialized a NodeJS project for the tutorial, you'll need to edit the newly created `package.json` file to add support for Modules. Open the `package.json` file in the Tutorial folder and add `"type": "module",` on a new line after `“main”:”index.js”` on line #5. ```js {6} { "name": "Tutorial", "version": "1.0.0", "description": "", "main": "index.js", "type": "module", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" } ``` Save the file and exit. ### Step 3: Install the 1Password SDK Finally, return to your terminal and install the 1Password JS SDK in the Tutorial folder: ```shell npm install @1password/sdk ``` ## Part 3: Build a JS application to fetch a secret from 1Password In this part of the tutorial, you'll build a simple JavaScript application to securely fetch your API credential secret from 1Password. Your application will authenticate to 1Password using the service account token you created in the previous section. ### Step 1: Import the SDK 1. Create a new file `index.js` in the Tutorial folder: ```shell touch index.js ``` 2. Copy and paste the following code into it: ``` // Creates an authenticated client. const client = await sdk.createClient({ auth: process.env.OP_SERVICE_ACCOUNT_TOKEN, // Set the following to your own integration name and version. integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); // Fetches a secret. const secret = await client.secrets.resolve("op://vault/item/field"); ``` 3. Save the file and return to the terminal. 4. Run the code: ```shell node index.js ``` You'll see an error because you haven't yet imported your service account token into the environment. This is necessary for 1Password SDKs to be able to access your vaults. ``` node:internal/process/esm_loader:40 internalBinding('errors').triggerUncaughtException( ^ missing field `serviceAccountToken` at line 1 column 252 (Use `node --trace-uncaught ...` to show where the exception was thrown) ``` ### Step 2: Import your service account token To import your service account token: 3. Copy and paste the following into your terminal to export the token to the environment. Don't run the code yet. **Bash, Zsh, sh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN= ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN ``` **PowerShell:** ```powershell $Env:OP_SERVICE_ACCOUNT_TOKEN = ``` 2. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 3. Navigate to the Tutorial vault and open the item for your service account token. 4. Select the service account token credential to copy it. 5. Paste the token into your terminal to complete the export command, then press <kbd>Enter</kbd>. **Bash, Zsh, sh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token> ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN <your-service-account-token> ``` **PowerShell:** ```powershell $Env:OP_SERVICE_ACCOUNT_TOKEN = "<your-service-account-token>" ``` 6. Run the following command to confirm you successfully set the environment variable: **Bash, Zsh, sh:** ```shell echo $OP_SERVICE_ACCOUNT_TOKEN ``` **fish:** ```shell echo $OP_SERVICE_ACCOUNT_TOKEN ``` **PowerShell:** ```powershell $Env:OP_SERVICE_ACCOUNT_TOKEN ``` Now try running the code again: ```shell node index.js ``` You'll get a new error, in this case because you didn't provide a reference path to a secret. Think of this like a URL for a secret within your vault. ``` error resolving secret reference: no vault matched the secret reference query ``` ### Step 3: Get a secret reference and resolve the secret To fix the above error, get the [secret reference URI](/docs/cli/secret-reference-syntax/) for your API credential and paste it into the code in place of the placeholder secret reference. 1. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 2. Open the Tutorial vault and select the API credential item you created earlier. 3. Select the down arrow next to the “credential" field, then select **Copy Secret Reference**. 4. In your `index.js` file, replace `op://vault/item/field` with the copied secret reference. _[]_ :::tip You can also get secret references with [1Password CLI](/docs/cli/secret-reference-syntax#with-1password-cli) and [1Password for VS Code](/docs/cli/secret-reference-syntax#with-1password-for-vs-code). ::: You should now see a secret reference that points to where the API credential is saved in your account: ```js {12} // Creates an authenticated client. const client = await sdk.createClient({ auth: process.env.OP_SERVICE_ACCOUNT_TOKEN, // Set the following to your own integration name and version. integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); // Fetches a secret. const secret = await client.secrets.resolve("op://Tutorial/API Credential/credential"); ``` Save the file and run the code again: ```shell node index.js ``` This time you won't see any errors, but you also won't see any output. You can fix this by adding some simple console logging. :::caution Logging an example secret is useful for testing, but please don't do this with production code. ::: 1. Reopen the `index.js` file and append the following line to output the secret to the console. ```shell console.log("The secret is: " + secret); ``` 2. Save and close the file, then run the code for a final time: ```shell node index.js ``` You should now see your API credential returned: ``` The secret is: example credential ``` ## Conclusion In this tutorial, you learned how to create a 1Password vault, item, and service account, and how to access your newly-created vault and item using the 1Password JavaScript SDK. Now that you have the basics down, you can extend this application to include other functions, like [updating the secret](/docs/sdks/manage-items#update-an-item). ## Learn more - [Get started with service accounts](/docs/service-accounts/get-started/) - [Get started with the 1Password JS SDK](https://github.com/1Password/onepassword-sdk-js?tab=readme-ov-file#-get-started) - [Get started with the 1Password Go SDK](https://github.com/1Password/onepassword-sdk-go?tab=readme-ov-file#-get-started) - [Get started with the 1Password Python SDK](https://github.com/1Password/onepassword-sdk-python?tab=readme-ov-file#requirements) --- ## Share items using 1Password SDKs You can use 1Password SDKs to securely share a copy of a 1Password item with anyone, even if they don't have a 1Password account. When you share an item, you'll get a unique link that you can send to others. You can choose when the link expires and who it's available to: anyone with the link, or only people with specific email addresses or email domains. You can also choose whether you want the link to be viewable only once, or multiple times. :::tip Make sure to add the `Share items` permission when creating your [service account token](/docs/service-accounts/) to share items using the SDKs. ::: ### Step 1: Retrieve the 1Password item you want to share **Go:** To retrieve the item you want to share, use the [`Items().Get()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L96) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. **JavaScript:** To retrieve the item you want to share, use the [`items.get()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L37) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. **Python:** To retrieve the item you want to share, use the [`items.get()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L74) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. ### Step 2: Fetch the item sharing account policy The item sharing account policy contains the allowed share settings that your account admin or owner has set. For individual and family accounts, these settings default to: - Unlimited views - All recipient types allowed - All share types allowed - Maximum share duration of 30 days - Default share duration of 7 days **Go:** To fetch the item sharing account policy, use the [`Items().Shares().GetAccountPolicy()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_shares.go#L31) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. **JavaScript:** To fetch the item sharing account policy, use the [`items.shares.getAccountPolicy()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_shares.ts#L47) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. **Python:** To fetch the item sharing account policy, use the [`items.shares.get_account_policy()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_shares.py#L17) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. ### Step 3: (Optional) Validate the recipients You can validate recipients to make sure that the people you want to share the link with are allowed to receive it, based on your account policy or sharing parameters. This step is only required if the item sharing link is limited to specific email addresses or domains. If the share link is accessible to anyone with the link, you can skip validating the recipients. **Go:** To validate the recipients, use the [`Items().Shares().ValidateRecipients()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_shares.go#L16) method. Replace `helloworld@agilebits.com` with the recipient's email address or domain in the example below. **JavaScript:** To validate the recipients, use the [`items.shares.validateRecipients()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_shares.ts#L72) method. Replace `helloworld@agilebits.com` with the recipient's email address or domain in the example below. **Python:** To validate the recipients, use the [`items.shares.validate_recipients()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_shares.py#L38) method. Replace `helloworld@agilebits.com` with the recipient's email address or domain in the example below. ### Step 4: Create the item sharing link :::tip Learn how to [view a shared item](https://support.1password.com/share-items#view-a-shared-item). ::: **Go:** Use the [`Items().Shares().Create()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_shares.go#L65) method to create a unique link you can send to others. This method requires an [`ItemShareParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L584) struct with the following fields: - `ExpireAfter`: How long the item link will remain accessible. Options include: `OneHour`, `OneDay`, `SevenDays`, `FourteenDays`, `ThirtyDays`. Not specifying this will default to the `DefaultShareDuration` in the account policy. - `Recipients`: The validated recipients of an item share, obtained through the recipient validation function. Leaving this parameter empty will allow everyone with the link to see the item. - `OneTimeOnly`: A boolean that determines if the link expires after one view. The SDK will create the link based on the configuration settings in the `ItemShareParams` struct. If you have a 1Password Business account, it will also validate the settings against the item sharing policy set by your account owner or administrator. The SDK returns a `shareLink` you can send to the person or people you want to share the item with. **JavaScript:** Use the [`items.shares.create()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_shares.ts#L30) method to create a unique link you can send to others. This method requires an [`ItemShareParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L445) object with the following properties: - `expireAfter`: How long the link will remain accessible. Options include: `OneHour`, `OneDay`, `SevenDays`, `FourteenDays`, `ThirtyDays`. Not specifying this will default to the `DefaultShareDuration` in the account policy. - `recipients`: An array of `ValidRecipient` objects. Leave empty to allow anyone with the link to view the shared item. - `oneTimeOnly:`: A boolean that determines if the link expires after a single view. The SDK will create the link based on the configuration settings in the `ItemShareParams` object. If you have a 1Password Business account, it will also validate the settings against the item sharing policy set by your account owner or administrator. The SDK returns a `share_link` you can send to the person or people you want to share the item with. **Python:** Use the [`items.shares.create()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_shares.py#L62) method to create a unique link you can send to others. This method requires an [`ItemShareParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L845) object with the following attributes: - `expireAfter`: How long the item share link will remain accessible. Options include: `OneHour`, `OneDay`, `SevenDays`, `FourteenDays`, `ThirtyDays`. Not specifying this will default to the `DefaultShareDuration` in the account policy. - `recipients`: An array of `ValidRecipient` objects. Leave empty to allow anyone with the link to view the shared item. - `oneTimeOnly:`: A boolean that determines if the link expires after a single view. The SDK will create your item share link based on the configuration settings in the `ItemShareParams` object. If you have a 1Password Business account, it will also validate the settings against the item sharing policy set by your account owner or administrator. The SDK returns a `share_link` you can send to the person or people you want to share the item with. --- ## 1Password SDK tutorials and examples ## Tutorials - **Set up the JS SDK and fetch a secret from 1Password**: Learn how to get started using a service account with the 1Password JavaScript SDK by building a simple app that securely fetches a secret from your 1Password account. Learn more - **Integrate 1Password SDKs with AI agents**: Learn a workflow for integrating 1Password SDKs with AI agents. Learn more ## Example projects - **Fetch an API key and authenticate to Twilio**: Build a simple app to read an API key from 1Password to use in your deployed services. Learn more - **Rotate an API key with AWS EventBridge**: Use 1Password SDKs with AWS EventBridge to automatically rotate secrets on a set schedule. Learn more - **Use 1Password as a backend for a web app**: Collect sensitive information using a web form, store it securely in 1Password, then display non-sensitive details on a webpage. Learn more - **Migrate data between 1Password tenants**: Create a web app that facilitates moving information between two 1Password accounts without writing any data to disk. Learn more - **Securely share files and markdown**: Create a 1Password item from files in a directory of your choice for the purposes of securely sharing source code and a README. Learn more - **Securely onboard employees to Okta**: Create a new Okta user and generate a strong password for their Okta account, then securely share the credentials with your new team member. Learn more --- ## Manage vault permissions using 1Password SDKs If you have [1Password Business](https://1password.com/business-security) or [1Password Teams](https://1password.com/product/teams-small-business-password-manager), you can manage your team members' vault access at the group level. We recommend authenticating with the [1Password desktop app](/docs/sdks/concepts#1password-desktop-app) to manage vault permissions. Service accounts can only manage permissions for vaults created by the service account. :::caution Some vault permissions require dependent permissions. You must grant or remove all required dependent permissions or the operation will fail. The permissions available to you depend on your account type. See [1Password Business vault permissions](#1password-business-vault-permissions) and [1Password Teams vault permissions](#1password-teams-vault-permissions) for more information. ::: > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for full example code you can quickly clone and test in your project. ## Grant vault permissions **Go:** Use the [`Vaults().GrantGroupPermissions()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L144) method to grant vault permissions to all team members who belong to a specific group. This method requires the following: - `vaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - A slice of one or more [`GroupAccess`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L129) structs that each contain: - `GroupID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `Permissions`: A bitmask of [vault permissions](#appendix-vault-permissions) to grant to the group. You can combine multiple permissions using the bitwise OR operator (`|`). **JavaScript:** Use the [`vaults.grantGroupPermissions()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L51) method to grant vault permissions to all team members who belong to a specific group. This method requires the following: - `vaultId`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - An array of one or more [`GroupAccess`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L133) objects that each contain: - `group_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `permissions`: A bitmask of [vault permissions](#appendix-vault-permissions) to grant to the group. You can combine multiple permissions using the bitwise OR operator (`|`). **Python:** Use the [`vaults.grant_group_permissions()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L155) method to grant vault permissions to all team members who belong to a specific group. This method requires the following: - `vault_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - A list of one or more [`GroupAccess`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L245) objects that each contains: - `group_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `permissions`: A bitmask of [vault permissions](#appendix-vault-permissions) to grant to the group. You can combine multiple permissions using the bitwise OR operator (`|`). ## Update vault permissions :::caution Make sure to specify **all** the permissions the group should have in the vault. This method completely replaces all existing permissions. ::: **Go:** Use the [`Vaults().UpdateGroupPermissions()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L153) method to replace a group's existing permissions in a vault. This method accepts a slice of one or more [`GroupVaultAccess`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L140) structs that each contains: - `VaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `GroupID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `Permissions`: A bitmask of the complete set of updated [vault permissions](#appendix-vault-permissions). You can combine multiple permissions using the bitwise OR operator (`|`). **JavaScript:** Use the [`vaults.updateGroupPermissions()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L59) method to replace a group's existing permissions in a vault. This method accepts an array of one or more [`GroupVaultAccess`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L147) objects that each contains: - `vaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `groupID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `permissions`: A bitmask of the complete set of updated [vault permissions](#appendix-vault-permissions). You can combine multiple permissions using the bitwise OR operator (`|`). **Python:** Use the [`vaults.update_group_permissions()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L181) method to replace a group's existing permissions in a vault. This method accepts a list of one or more [`GroupVaultAccess`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L269) objects that each contains: - `vault_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `group_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `permissions`: A bitmask of the complete set of updated [vault permissions](#appendix-vault-permissions). You can combine multiple permissions using the bitwise OR operator (`|`). ## Revoke vault permissions **Go:** Use the [`Vaults().RevokeGroupPermissions()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L161) method to completely remove a group's access to a vault. This method requires the following: - `vaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `groupID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group whose permissions you want to revoke. **JavaScript:** Use the [`vaults.revokeGroupPermissions()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L66) method to completely remove a group's access to a vault. This method requires the following: - `vaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `groupID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group whose permissions you want to revoke. **Python:** Use the [`vaults.revoke_group_permissions()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L204) method to completely remove a group's access to a vault. This method requires the following: - `vault_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `group_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group whose permissions you want to revoke. ## Appendix: Vault permissions The permissions available to you depend on your account type: [1Password Business](#1password-business-vault-permissions) or [1Password Teams](#1password-teams-vault-permissions). ### 1Password Business vault permissions In 1Password Business, all vault permissions have a hierarchical relationship in which narrower permissions require broader permissions to be granted alongside them. For example, to grant the narrower permission `DELETE_ITEMS` you must also grant the broader permissions `EDIT_ITEMS`, `REVEAL_ITEM_PASSWORD`, and `READ_ITEMS`. This is because you cannot delete items unless you can also view and edit them. Similarly, to revoke a broader permission like `READ_ITEMS`, any narrower dependent permissions like `DELETE_ITEMS` that have already been granted must also be revoked. | Permission | Description | Required dependencies | Integer | | --- | --- | --- | --- | | `READ_ITEMS` | View items in the vault. | None | 32 | | `CREATE_ITEMS` | Create items in the vault. | `READ_ITEMS` | 128 | | `REVEAL_ITEM_PASSWORD` | View and copy concealed password fields in the vault. | `READ_ITEMS` | 16 | | `UPDATE_ITEMS` | Edit items in the vault. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD` | 64 | | `ARCHIVE_ITEMS` | Move items in the vault to the Archive. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEMS` | 256 | | `DELETE_ITEMS` | Delete items in the vault. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEMS` | 512 | | `UPDATE_ITEM_HISTORY` | View and restore item history. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD` | 1024 | | `IMPORT_ITEMS` | Move or copy items into the vault. | `READ_ITEMS`, `CREATE_ITEMS` | 2097152 | | `EXPORT_ITEMS` | Save items in the vault to an unencrypted file that other apps can read. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEM_HISTORY` | 4194304 | | `SEND_ITEMS` | Copy and share items. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEM_HISTORY` | 1048576 | | `PRINT_ITEMS` | Print the contents of items in the vault. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEM_HISTORY` | 8388608 | | `MANAGE_VAULT` | Grant and revoke access to the vault, change permissions for others, and delete the vault. This permission doesn’t include any item viewing or editing permissions. | None | 2 | | `NO_ACCESS` | Grants a group access entry to a vault without any permissions in it. | | 0 | ### 1Password Teams vault permissions 1Password Teams includes three broad permission levels made up of collections of the [granular vault permissions](#1password-business-vault-permissions) available in 1Password Business. You'll need to grant or revoke all the permissions for the desired permission level. The permission levels have a hierarchical relationship. To grant `Allow editing`, you must also grant the permissions included in `Allow viewing`. | Permission | Description | Includes permissions | | --- | --- | --- | | Allow viewing | View items in a vault, view concealed passwords and copy them to the clipboard. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEM_HISTORY` | | Allow editing | Create, edit, move, print, copy, archive, and delete items in the vault. Requires the `Allow viewing` permission level to be granted. | `CREATE_ITEMS`, `UPDATE_ITEMS`, `ARCHIVE_ITEMS`, `DELETE_ITEMS`, `IMPORT_ITEMS`, `EXPORT_ITEMS`, `SEND_ITEMS`, `PRINT_ITEMS` | | Allow managing | Grant and revoke access to the vault, change permissions for others, and delete the vault. | `MANAGE_VAULT` | --- ## Manage vaults using 1Password SDKs You can use 1Password SDKs to manage [vaults](https://support.1password.com/1password-glossary#vault) in 1Password. You can only get information about vaults the authenticated user has access to, and you can only manage vaults where you have the [Manage Vault permission](/docs/sdks/vault-permissions#appendix-vault-permissions). We recommend authenticating with the [1Password desktop app](/docs/sdks/concepts#1password-desktop-app) to manage vaults. Service accounts are scoped to specific vaults, and must have explicit permission to create new vaults. Service accounts can't update existing vaults and can only delete vaults created by the service account. > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for full example code you can quickly clone and test in your project. ## Create a vault :::tip If you're authenticating with a service account, make sure the service account has permission to create vaults. If it doesn't have permission to create vaults, you'll need to [create a new service account](/docs/service-accounts/get-started#create-a-service-account) with this permission or authenticate using [the 1Password desktop app](/docs/sdks/concepts#1password-desktop-app). ::: **Go:** Use the [`Vaults().Create()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L50) method to create a new vault. This method requires a [`VaultCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1040) struct with the following fields: - `Title`: The name of the vault. - `Description`: An optional pointer to a string containing the vault's description. Returns: A [`Vault`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1021) struct. **JavaScript:** Use the [`vaults.create()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L79) method to create a new vault. This method requires an options object with the following properties: - `title`: The name of the vault. - `description`: An optional description for the vault. Returns: A Promise that resolves to a [`Vault`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L568) object. **Python:** Use the [`vaults.create()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L28) method to create a new vault. This method requires a [`VaultCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1310) object with the following parameters: - `title`: The name of the vault. - `description`: An optional description for the vault. - `allow_admins_access`: A boolean that determines whether people who belong to the [Administrators](https://support.1password.com/1password-glossary/#administrator) group can access the vault. Returns: A [`Vault`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1269) object. ## Get a vault overview **Go:** Use the [`Vaults().GetOverview()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L86) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to retrieve high-level metadata about the vault. The following example gets the overview for the vault you created [in the previous step](#create-a-vault). **JavaScript:** Use the [`vaults.getOverview()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L31) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to retrieve high-level metadata about the vault. The following example gets the overview for the vault you created [in the previous step](#create-a-vault). **Python:** Use the [`vaults.get_overview()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L72) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to retrieve high-level metadata about the vault. The following example gets the overview for the vault you created [in the previous step](#create-a-vault). ## Get vault details **Go:** Use the [`Vaults().Get()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L102) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to get the vault's full metadata. The following example gets details for the vault you retrieved [in the previous step](#get-a-vault-overview). **JavaScript:** Use the [`vaults.get()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L36) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to get the vault's full metadata. The following example gets details for the vault you created [in the first step](#create-a-vault). **Python:** Use the [`vaults.get()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L91) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to get the vault's full metadata. ## Update a vault **Go:** Use the [`Vaults().Update()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L119) method to modify the details of an existing vault. This method requires the following: - `vaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to update. - A [`VaultUpdateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1076) struct that contains the new vault details: - `Title`: The new name for the vault. - `Description`: An updated description for the vault. Returns: The updated [`Vault`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1021) struct. The following example updates the name and description of the vault you created [in the first step](#create-a-vault). **JavaScript:** Use the [`vaults.update()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L167) method to modify the details of an existing vault. This method requires the following: - `vaultId`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to update. - An object that contains the new vault details: - `title`: The new name for the vault. - `description`: An updated description for the vault. Returns: A Promise that resolves to the updated [`Vault`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L568) object. The following example updates the name and description of the vault you created [in the first step](#create-a-vault). **Python:** Use the [`vaults.update()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L113) method to modify the details of an existing vault. This method requires the following: - `vault_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to update. - A [`VaultUpdateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1388) object that contains the new vault details: - `title`: The new name for the vault. - `description`: An updated description for the vault. Returns: The updated [`Vault`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1269) object. The following example updates the name and description of the vault you created [in the first step](#create-a-vault). ## Delete a vault **Go:** To delete a vault, use the [`Vaults().Delete()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L136) method with the [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to delete. The following example deletes the vault you created [in the first step](#create-a-vault). **JavaScript:** To delete a vault, use the [`vaults.delete()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L46) method with the [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to delete. The following example deletes the vault you created [in the first step](#create-a-vault). **Python:** To delete a vault, use the [`vaults.delete()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L135) method with the [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to delete. The following example deletes the vault you created [in the first step](#create-a-vault). :::tip You can also [batch create, get, and delete items](/docs/sdks/manage-items#manage-items-in-bulk) from a vault. ::: ## Learn more - [Manage items in bulk](/docs/sdks/manage-items#manage-items-in-bulk) - [Manage vault permissions](/docs/sdks/vault-permissions) - [List vaults and items](/docs/sdks/list-vaults-items) --- ## Advanced use cases ## Gradual migration ### Mac & Linux If you don't want to use the 1Password SSH agent for all your hosts right away, you don't have to. The 1Password SSH agent can run alongside another SSH agent, like the OpenSSH agent. The SSH client config file (`~/.ssh/config`) allows you to provide different authentication details for different hosts. So, you can try the 1Password SSH agent with one or two hosts to start, then gradually migrate the rest when you're ready. Here are a few examples of what your `~/.ssh/config` file could look like: **Example 1:** ```toml # A host that uses the 1Password agent Host raspberry-pi HostName 192.168.12.34 User pi IdentityAgent ~/.1password/agent.sock # A host that uses a local private key file that isn't saved in 1Password Host ec2-server HostName 54.123.45.67 User ec2-user IdentityFile ~/.ssh/ssh-key-not-on-1password.pem ``` **Example 2:** ```toml # By default, use the 1Password SSH agent for all hosts Host * IdentityAgent ~/.1password/agent.sock # A host that uses a local private key file that isn't saved in 1Password Host ec2-server HostName 54.123.45.67 User ec2-user IdentityFile ~/.ssh/ssh-key-not-on-1password.pem IdentityAgent none ``` **Example 3:** ```toml # By default, use a local private key file that's not saved in 1Password Host * IdentityFile ~/.ssh/ssh-key-not-on-1password.pem # Use the 1Password agent on a single host instead of the local key file Host raspberry-pi HostName 192.168.12.34 User pi IdentityAgent ~/.1password/agent.sock IdentityFile none ``` ### Windows No changes to the SSH configuration need to be made on Windows. Windows doesn't have the same flexibility with the `~/.ssh/config` file as macOS and Linux, because Microsoft OpenSSH listens to a fixed pipe `(\\.\pipe\openssh-ssh-agent)`. If you want to use the 1Password SSH agent on Windows, it will authenticate for all hosts. ## SSH server six-key limit :::tip Use [SSH bookmarks](/docs/ssh/bookmarks/) to match your SSH hosts with SSH keys and avoid server key limitations. ::: SSH agents work together with SSH clients by trying all public keys the agents manage, offering them one by one to SSH servers until the server acknowledges one that works. However, OpenSSH servers are configured by default to limit the amount of authentication attempts for an incoming SSH connection (`MaxAuthTries`) to six. If your SSH client offers the SSH server a seventh key, the server will refuse the connection and you'll see this error message in your SSH client: ```text Too many authentication failures ``` Server administrators *can* increase the limit by setting `MaxAuthTries` in the [server's `/etc/ssh/sshd_config`](https://linux.die.net/man/5/sshd_config), but in many cases you can't (or don't want to) change this. Instead, you can specify which host should be matched to which SSH key. ### Match key with host To avoid the `Too many authentication failures` error, your SSH client needs to know which SSH public key should be used with which host. This can be configured in the SSH config file by setting `IdentityFile` in a `Host` block to the public key you want use with that host. You can configure [SSH Bookmarks](/docs/ssh/bookmarks/) to automatically manage this for you. Alternatively, you can manually edit your SSH config file: 1. In your 1Password app, select the **Download** button on the "Public key" field of the SSH item. 2. In your `~/.ssh/config` file, add an entry for the host you're connecting to and set `IdentityFile` to the path of the **public key** you just downloaded. The private key can stay in 1Password. ```toml Host github.com IdentityFile ~/.ssh/public-key-downloaded-from-1password.pub IdentitiesOnly yes ``` Now your SSH clients will know which key to use when connecting to SSH servers, so you won't run into these authentication limits. :::warning[caution] Some SSH clients don't support specifying public keys in `IdentityFile`. See [SSH client compatibility](/docs/ssh/agent/compatibility/). ::: ### Create an SSH agent config file You can also create an optional [SSH agent config file](/docs/ssh/agent/config/) (`~/.config/1Password/ssh/agent.toml`). The agent config file allows you to specify which keys the SSH agent can make available to SSH servers and the order it offers those keys to servers. You can use the SSH agent config file alongside your SSH client config file (`~/.ssh/config`) to help further avoid authentication limits. ## Use multiple Git identities on the same machine When you connect to remote Git repositories from your local machine, all connections that are authenticated over SSH use the same `git` user. If you want to use SSH with multiple Git identities on the same machine, such as a work and personal account, you'll need to: - Define SSH host aliases for the different Git identities in your SSH config file. - Configure which SSH keys are used to authenticate connections to the remote Git repositories. - Update the URLs for your Git remotes to use the new SSH host aliases. To get started, follow these steps: 1. In the 1Password app, locate the SSH Key item for one of your Git accounts. 2. Select the down arrow on the "public key" field and choose **Download**. _[Download your public key]_ 3. Save the public key to your `~/.ssh/` directory. 4. Repeat steps 1–3 for each SSH key you need to use. 5. On your local machine, edit your `~/.ssh/config` file to add SSH host sections for each Git identity. For example, to configure SSH hosts for your personal and work GitHub accounts, you would add the following to your SSH config file: ```text title="~/.ssh/config" # Personal GitHub Host personalgit HostName github.com User git IdentityFile ~/.ssh/personal_git.pub IdentitiesOnly yes # Work GitHub Host workgit HostName github.com User git IdentityFile ~/.ssh/work_git.pub IdentitiesOnly yes ``` You can adjust the host (the alias name) and hostname, if needed, and you'll need to set `IdentityFile` to use the public key you saved in your `~/.ssh/` directory for that repository. 6. For each Git repository, change the `git` URL to use one of the new SSH host aliases instead of the default host URL, such as `git@github.com`. ```bash git remote set-url origin <host>:<workplace>/<repo>.git ``` For example: ```bash git remote set-url origin personalgit:1password/1password-teams-open-source.git ``` Now your SSH clients will know which SSH key to use for each Git identity. Learn more about how to [sign Git commits with SSH](/docs/ssh/git-commit-signing/). --- ## SSH client compatibility The 1Password SSH agent has been tested for compatibility with a number of different clients that use SSH and Git. **Mac:** | Name | SSH Capability | Compatible with 1Password | | --- | --- | --- | | **[Cyberduck](#cyberduck)** | SFTP | ✅ Yes | | **[DataGrip](#datagrip)** | SSH tunneling | ✅ Yes | | **[FileZilla](#filezilla)** | SFTP | ✅ Yes | | **[Fork](#fork)** | Git | ✅ Yes | | **[ForkLift](#forklift)** | SFTP | ✅ Yes | | **[git CLI](#git-cli)** | Git | ✅ Yes | | **[Gitfox](#gitfox)** | Git | ✅ Yes | | **[GitHub Desktop](#github-desktop)** | Git | ✅ Yes | | **[GitKraken](#gitkraken)** | Git | ✅ Yes | | **GitUp** | Git | ✅ Yes | | **[JetBrains IDEs](#jetbrains-ide)** | Git | ✅ Yes | | **[Nova](#nova)** | Git | ✅ Yes | | **[OpenSSH](#openssh)** | SSH, SFTP | ✅ Yes | | **[Postico](#postico)** | SSH tunneling | ❌ No | | **[Sequel Ace](#sequel-ace)** | SSH tunneling | ❌ No | | **[Sourcetree](#sourcetree)** | Git | ✅ Yes | | **[Sublime Merge](#sublime-merge)** | Git | ✅ Yes | | **[TablePlus](#tableplus)** | SSH tunneling | ✅ Yes | | **[Termius](#termius)** | SSH | ❌ No | | **[Tower](#tower)** | Git | ✅ Yes | | **[Transmit](#transmit)** | SFTP | ✅ Yes | | **[Visual Studio Code](#vs-code)** | Git | ✅ Yes | | **[Xcode](#xcode)** | Git | ❌ No | **Windows:** | Name | SSH Capability | Compatible with 1Password | | --- | --- | --- | | **[Celestial Software](#celestial-software)** | SSH, SFTP | ✅ Yes | | **[Cyberduck](#cyberduck)** | SFTP | ✅ Yes | | **[FileZilla](#filezilla)** | SFTP | ❌ No | | **[Fork](#fork)** | Git | ✅ Yes | | **[Git for Windows](#git-for-windows)** | Git | ✅ Yes | | **[GitHub Desktop](#github-desktop)** | Git | ✅ Yes | | **[GitKraken](#gitkraken)** | Git | ✅ Yes | | **[JetBrains IDEs](#jetbrains-ide)** | Git | ✅ Yes | | **[Microsoft OpenSSH](#openssh)** | SSH, SFTP | ✅ Yes | | **[Pageant](#pageant)** | SSH | ❌ No | | **[PuTTY](#putty)** | SSH | ❌ No | | **[Sourcetree](#sourcetree)** | Git | ✅ Yes | | **[Sublime Merge](#sublime-merge)** | Git | ✅ Yes | | **[Termius](#termius)** | SSH | ❌ No | | **[Tower](#tower)** | Git | ✅ Yes | | **[Visual Studio Code](#vs-code)** | Git | ✅ Yes | **Linux:** | Name | SSH Capability | Compatible with 1Password | | --- | --- | --- | | **[DataGrip](#datagrip)** | SSH tunneling | ✅ Yes | | **[git CLI](#git-cli)** | Git | ✅ Yes | | **[GitKraken](#gitkraken)** | Git | ✅ Yes | | **[JetBrains IDEs](#jetbrains-ide)** | Git | ✅ Yes | | **[OpenSSH](#openssh)** | SSH, SFTP | ✅ Yes | | **[Sublime Merge](#sublime-merge)** | Git | ✅ Yes | | **[Termius](#termius)** | SSH | ❌ No | | **[Visual Studio Code](#vs-code)** | Git | ✅ Yes | // Args children, icon, prefixText, // Flags noPrefix, // Templates authSock, identityAgent, identityFile, commitSigning, gitBinarySetting, jetbrainsSocketCaveat, macAppStore, windowsPipe, windowsPipeWithGitconfig, pageantOnly, anySSHAgent }) => { const text = () => { if (authSock) { return {prefixText} agent configuration with `SSH_AUTH_SOCK`.; } if (windowsPipe) { return {prefixText} using the agent over the OpenSSH pipe (`\\.\pipe\openssh-ssh-agent`).; } if (windowsPipeWithGitconfig) { return {prefixText} using the agent over the OpenSSH pipe with the `.gitconfig` file set up properly.; } if (identityAgent) { return {prefixText} agent configuration with `IdentityAgent`.; } if (identityFile) { return {prefixText} setting public keys as `IdentityFile`.; } if (commitSigning) { return {prefixText} signing Git commits with SSH keys.; } if (gitBinarySetting) { return You may need to switch the Git binary in the preferences.; } if (jetbrainsSocketCaveat) { return If you're seeing errors around the socket path, go to `Advanced Settings` > `SSH` and set `Configuration files parser` to `OpenSSH`.; } if (macAppStore) { return {prefixText} the Mac App Store version.; } if (pageantOnly) { return No support for SSH agents over the OpenSSH pipe, only works with Pageant.; } if (anySSHAgent) { return {prefixText} any SSH agent. Uses a built-in key management system.; } if (noPrefix) { return {children}; } return {prefixText} {children}; } return ( {icon} {text.apply()} ) }; return } prefixText="Support for" {...props} /> }; return } prefixText="No support for" {...props} /> }; return } prefixText="" {...props} /> }; return } prefixText="" {...props} /> }; // This should not be displayed to customers // return return }; --- ## Working with SSH clients ### Agent configuration with `IdentityAgent` {#identity-agent} On Mac and Linux, most SSH and Git clients check your `~/.ssh/config` file for the `IdentityAgent` setting for the corresponding host. The clients then use the configured agent socket path to handle SSH authentication. This option gives you the most flexibility, like the ability to configure [multiple agents side by side](/docs/ssh/agent/advanced#gradual-migration). However, not every SSH client adheres to every value in the SSH config file. In the list below, you can see whether or not your SSH client supports configuration with `IdentityAgent`. ### Agent configuration with `SSH_AUTH_SOCK` {#ssh-auth-sock} On Mac and Linux, you can also configure the agent socket path using the `SSH_AUTH_SOCK` environment variable. There are more SSH clients that support `SSH_AUTH_SOCK` than `IdentityAgent`. For clients that support both, `IdentityAgent` usually takes precedence over `SSH_AUTH_SOCK`. Follow the steps for your operating system to configure `SSH_AUTH_SOCK` for your SSH client: **Mac:** #### Configure `SSH_AUTH_SOCK` for the terminal To configure `SSH_AUTH_SOCK` for the terminal, run: ``` export SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ``` Any command you run within that same shell will use the 1Password SSH agent. To pass `SSH_AUTH_SOCK` to a GUI application, you can use the `open` command to launch the application: ```shell export SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock open -a /Applications/<your SSH client>.app ``` #### Configure `SSH_AUTH_SOCK` globally for every client If you want to persist and automatically configure the `SSH_AUTH_SOCK` environment variable for every client without launching them from the terminal, run the following snippet to create a launch agent: ```shell mkdir -p ~/Library/LaunchAgents cat << EOF > ~/Library/LaunchAgents/com.1password.SSH_AUTH_SOCK.plist <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.1password.SSH_AUTH_SOCK</string> <key>ProgramArguments</key> <array> <string>/bin/sh</string> <string>-c</string> <string>/bin/ln -sf $HOME/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock \$SSH_AUTH_SOCK</string> </array> <key>RunAtLoad</key> <true/> </dict> </plist> EOF launchctl load -w ~/Library/LaunchAgents/com.1password.SSH_AUTH_SOCK.plist ``` **Linux:** #### Configure `SSH_AUTH_SOCK` for the terminal To configure `SSH_AUTH_SOCK` for the terminal, run: ``` export SSH_AUTH_SOCK=~/.1password/agent.sock ``` Any command you run within that same shell will use the 1Password SSH agent. #### Configure `SSH_AUTH_SOCK` globally for every client If you want to persist and automatically configure the `SSH_AUTH_SOCK` environment variable for every client without launching them from the terminal, run the following snippet to create a login script in `/etc/profile.d/`: ```shell echo "export SSH_AUTH_SOCK=~/.1password/agent.sock" | sudo tee /etc/profile.d/1password-ssh-auth-sock.sh ``` If your system launches the GNOME keyring SSH agent automatically, you can disable that by running the following command: ```shell mkdir -p ~/.config/autostart \ && cp /etc/xdg/autostart/gnome-keyring-ssh.desktop ~/.config/autostart/gnome-keyring-ssh.desktop \ && echo "Hidden=true" >> ~/.config/autostart/gnome-keyring-ssh.desktop ``` If you choose not to do this, the GNOME setting (`/run/user/1000/keyring/ssh`) may take precedence over the 1Password setting, depending on your operating system. ### Using Git autofetch {#git-autofetch} Some Git clients are configured by default to periodically perform a `git fetch` in the background. This can result in authorization prompts popping up unexpectedly, so 1Password helps to suppress prompts if the application or window where the request came from isn't in the foreground. If a prompt has been suppressed, you'll see an indicator dot on the 1Password icon in your device's menu bar, taskbar, or system tray. To access the prompt, select the 1Password icon, then select **SSH request waiting**. The authorization prompt will be brought to the foreground, where you can approve or deny the request. If you'd rather not be prompted when your applications automatically fetch changes, even when the prompts are suppressed, you can turn off the autofetch settings in your Git client and instead only fetch or pull on demand. _[Turn on the settings in 1Password to make sure the agent keeps running]_ ### Setting public keys as `IdentityFile` {#identity-file} If an SSH client supports setting public keys as `IdentityFile`, you can use that to [match hosts to a specific key in 1Password](/docs/ssh/agent/advanced#match-key-with-host). In the list below, you can see if that's the case for your preferred SSH client. --- ## OpenSSH {#openssh} **Mac:** #### `ssh`, `sftp`, `scp` workflows with jump hosts (`-J`, `ProxyJump`, `ProxyCommand`). workflows that use agent forwarding (`ForwardAgent`). #### `ssh-add` listing identities (`-l` and `-L`). locking and unlocking (`-x` and `-X`). adding and deleting identities (`ssh-add path/to/key`, `-d`, and `-D`). **Windows:** #### `ssh`, `sftp`, `scp` #### `ssh-add` listing identities (`-l` and `-L`). locking and unlocking (`-x` and `-X`). adding and deleting identities (`ssh-add path/to/key`, `-d`, and `-D`). **Linux:** #### `ssh`, `sftp`, `scp` workflows with jump hosts (`-J`, `ProxyJump`, `ProxyCommand`). workflows that use agent forwarding (`ForwardAgent`). #### `ssh-add` listing identities (`-l` and `-L`). locking and unlocking (`-x` and `-X`). adding and deleting identities (`ssh-add path/to/key`, `-d`, and `-D`). ## Celestial Software {#celestial-software} **Windows:** ## Cyberduck {#cyberduck} **Mac:** **Windows:** ## DataGrip {#datagrip} **Mac:** **Linux:** ## FileZilla {#filezilla} **Mac:** **Windows:** ## Fork {#fork} **Mac:** **Windows:** ## ForkLift {#forklift} **Mac:** ## `git` CLI **Mac:** **Windows:** For Git compatibility on Windows, see [Git for Windows](#git-for-windows). **Linux:** ## Git for Windows {#git-for-windows} **Windows:** PowerShell and `cmd`. > **Tip:** > For WSL, workarounds exist to forward socket connections using `npiperelay` and `socat`. ## Gitfox {#gitfox} **Mac:** ## GitHub Desktop {#github-desktop} **Mac:** **Windows:** using it when GitHub account is connected/logged in. ## GitKraken {#gitkraken} **Mac:** **Windows:** **Linux:** ## JetBrains IDEs {#jetbrains-ide} *IntelliJ IDEA, WebStorm, GoLand, CLion, PhpStorm, RubyMine, AppCode.* **Mac:** **Windows:** **Linux:** ## Nova {#nova} **Mac:** ## Pageant {#pageant} **Windows:** using the agent from Pageant. > **Tip:** > Workarounds and open-source tools exist to forward Pageant requests to the OpenSSH agent pipe. ## Postico {#postico} **Mac:** > **Tip:** > As a workaround, you can set up the SSH tunnel from your terminal and then configure Postico to connect over `localhost`. ## PuTTY {#putty} **Windows:** ## Sequel Ace {#sequel-ace} **Mac:** > **Tip:** > As a workaround, you can set up the SSH tunnel from your terminal and then configure Sequel Ace to connect over `localhost`. ## Sourcetree {#sourcetree} **Mac:** **Windows:** ## Sublime Merge {#sublime-merge} **Mac:** **Windows:** **Linux:** ## TablePlus {#tableplus} **Mac:** {/* **Windows:** */} {/* **Linux:** */} ## Termius {#termius} **Mac:** **Windows:** **Linux:** ## Tower {#tower} **Mac:** **Windows:** using it when GitHub account is connected/logged in. ## Transmit {#transmit} **Mac:** ## Visual Studio Code {#vs-code} **Mac:** **Windows:** **Linux:** ## Xcode {#xcode} **Mac:** --- ## SSH agent config file The 1Password SSH agent config file is a [TOML file](https://toml.io/en/) you can create that gives you more fine-grained control over the behavior of the SSH agent. With the agent config file, you can: - [Choose which keys are available to the SSH agent](#add-individual-keys) from any of your vaults and accounts, not just your Personal, Private, or Employee vault. - Specify the order the agent uses to offer your keys to SSH servers, to prevent running into the [six-key authentication limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit) on most servers. - Create different agent configurations for each machine, to customize how you use the SSH agent on each device. The SSH agent config file (`~/.config/1Password/ssh/agent.toml`) is unique to 1Password. It's separate from the SSH *client* config file ([`~/.ssh/config`](https://linux.die.net/man/5/ssh_config)) and the SSH *server* config file ([`/etc/ssh/sshd_config`](https://linux.die.net/man/5/sshd_config)) and can be used alongside them. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) 4. [Set up the 1Password SSH Agent.](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) ## About the SSH agent config file The SSH agent config file is an optional configuration file that allows you to override the [default behavior](#agent-configuration-options) of the 1Password SSH agent on your Mac, Windows, or Linux machine. It doesn't alter your SSH agent settings or other SSH config files on your computer — only which keys the agent can access and in which order to make them available to servers. The agent config file is saved locally on your machine and isn't synced to the 1Password servers. If you use 1Password with multiple workstations, you can sync or share the agent config file using your own method (for example, using Git) the same way you do with other dotfiles. Or you can create separate agent config files for each machine. You can [remove the agent config file](#remove-the-ssh-agent-config-file) at any time to return to the default agent configuration. ### Agent configuration options If there's no agent config file on your machine, 1Password will use the default SSH agent configuration, which allows the agent to make any SSH key item in your default [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault available to offer to SSH servers. If you want to customize how the SSH agent is configured, you can [create the SSH agent config file](#create-the-ssh-agent-config-file) to override the default agent behavior, then [modify the file](#modify-the-ssh-agent-config-file) to specify which keys the SSH agent has access to and the order you want them offered to the server. ### File syntax and structure #### TOML syntax The SSH agent config file uses the [TOML file syntax](https://toml.io/en/v1.0.0) to identify which SSH keys the SSH agent can access and when it can access them. Each entry in the file requires an `[[ssh-keys]]` header and one or more key-value pairs to indicate the item, vault, and/or account name or ID for the SSH key item. For example: ```toml title=agent.toml # Add my Git authentication key from my Work vault [[ssh-keys]] item = "Git Authentication Key" vault = "Work" # Add my Git signing key from my Work vault [[ssh-keys]] item = "Git Signing Key" vault = "Work" # Then add all keys from my Private vault [[ssh-keys]] vault = "Private" account = "Wendy Appleseed's Family" ``` **TOML syntax rules** The SSH agent config file adheres to the following TOML syntax rules: - **Case sensitivity:** TOML is case-sensitive, so all TOML elements (the header name and keys in key-value pairs) must be lowercase. Strings (1Password values enclosed in quotation marks) and comments are not case-sensitive. - **Encoding:** The TOML file must use valid [UTF-8 character encoding](https://www.ietf.org/rfc/rfc3629.txt). - **Comments:** Use the hash (#) symbol to indicate the line is a comment. Comments are optional and are not case-sensitive. For example: ``` # This line is a comment. ``` - **Header name:** Indicates the start of a new section and must be lowercase and enclosed in double brackets to indicate an array of tables. Each header must use the same name `[[ssh-keys]]` header name to define it as part of the array. - **Key-value pairs:** Indicate which SSH key items are available to the SSH agent. Keys must be lowercase and can be one or more of `item`, `vault`, or `account`. Values are the strings containing the item, vault, or account name or ID from 1Password and must be enclosed in quotes. Key-value pairs are separated by an equal (=) sign and each pair must be on a new line. Unspecified values are invalid. For example: ``` item = "My SSH key item name" ``` - **Whitespace:** Leading and trailing whitespace of both `key` and `value` segments are ignored, so `key = "value"` is parsed the same as `key="value"`. #### Examples of good TOML file entries ```toml variant="good" # My work GitHub SSH key [[ssh-keys]] item = "GitHub SSH key - Work" ``` The example above meets all the syntax criteria. ```toml variant="good" # My team's demo GitHub SSH key [[ssh-keys]] item="GitHub SSH key - Demo" vault="Demo" account="AgileBits" ``` Whitespace is ignored for key-value pairs, so this example is also good. #### Examples of bad TOML file entries ```toml variant="bad" # My work GitHub SSH key [[SSH-KEYS]] ITEM = "GitHub SSH key - Work" ``` The example above doesn't respect the case sensitivity for TOML elements — `[[ssh-keys]]` and `item` need to be lowercase. ```toml variant="bad" # My work GitHub SSH key item = "github ssh key - work" ``` In this example, the `"github ssh key - work"` value is good because 1Password values aren't case sensitive, but the entry is missing the required `[[ssh-keys]]` header. ```toml variant="bad" # My team's demo GitHub SSH key [[ssh-keys]] item = GitHub SSH key - Demo vault = Demo account = AgileBits ``` In the example above, the values for `item`, `vault`, and `account` aren't enclosed in quotations. For more information about TOML, see the [full list of specifications](https://toml.io/en/v1.0.0). #### File structure The SSH agent config file is made up of sections. A section is defined by the `[[ssh-keys]]` header followed by one or more key-value pairs for the intended SSH key or set of keys to be made available to the SSH agent. The order of the `[[ssh-keys]]` sections in the agent config file determine the order the agent offers your keys to SSH servers. This helps to minimize the number of authentication attempts the SSH agent makes so you don't run into the [six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit) (`MaxAuthTries`) that is the default for most SSH servers. Here's an example of an SSH agent configuration file with entries for two specific SSH keys: ```toml agent.toml {3,9} # My GitHub SSH key for my Work account [[ssh-keys]] item = "GitHub SSH key - Work" vault = "Private" account = "AgileBits" # Shared GitHub SSH key for the Demo account [[ssh-keys]] item = "GitHub SSH Key - Demo" vault = "Demo" account = "AgileBits" ``` With this configuration, if you try to SSH into a GitHub repository in your `Work` account, the SSH agent will offer your work SSH key to the server first because it's the first key entry in the file. If the key is a match, 1Password will ask you to [authorize the request](/docs/ssh/get-started#step-6-authorize-the-ssh-request). If you try to SSH into a GitHub repository in your `Demo` account instead, the agent will still offer your work key to the server first, then your demo SSH key. With only two SSH keys in the file, it's unlikely that you'd be at risk of running into any server limits. However, if you have six or more SSH keys listed in your agent config file before the demo key, or if your agent config file includes multiple SSH keys for the same host, you can also modify the SSH client config file (`~/.ssh/config`) to [match your SSH keys to individual hosts](/docs/ssh/agent/advanced#match-key-with-host) or specify [which SSH key each of your GitHub repositories uses](/docs/ssh/agent/advanced#use-multiple-git-identities-on-the-same-machine). ## Create the SSH agent config file ### From the 1Password app You can use the 1Password desktop app to create the SSH agent config file for you. The file will include entries to allow the SSH agent to access all the keys in any of your Personal, Private, or Employee vaults, similar to the [default configuration](#agent-configuration-options) used by the agent when no agent config file exists. For example, if you're signed in to a 1Password account with a default Private vault, you'll see an entry like this added to the agent config file: ```toml [[ssh-keys]] vault = "Private" ``` You can then choose to [modify the file](#modify-the-ssh-agent-config-file) to adjust which keys the agent offers to SSH servers in which order. To create the agent config file from 1Password: **Mac:** 1. Open and unlock [1Password for Mac](https://1password.com/downloads/mac) and select any SSH key you want to add to the agent config file. If you don't have any SSH keys saved in 1Password yet, you can generate a new key in 1Password or import an existing key. 2. Select > **Configure for SSH Agent**. This will automatically create the SSH agent config file and open it in your default editor. You can then [modify the config file](#modify-the-ssh-agent-config-file) to add the SSH key. _[Create the SSH agent config file from the app]_ On macOS, 1Password will create the SSH agent config file in the following location: ```text ~/.config/1Password/ssh/agent.toml ``` 1Password also supports the `XDG_CONFIG_HOME` environment variable, if you have it configured. After you create the file, you may need to lock and then unlock 1Password for the agent config file to be recognized. **Windows:** 1. Open and unlock [1Password for Windows](https://1password.com/downloads/windows) and select any SSH key you want to add to the agent config file. If you don't have any SSH keys saved in 1Password yet, you can generate a new key in 1Password or import an existing key. 2. Select > **Configure for SSH Agent**. This will automatically create the SSH agent config file and open it in your default editor. You can then [modify the config file](#modify-the-ssh-agent-config-file) to add the SSH key. _[Create the SSH agent config file from the app]_ On Windows, 1Password will create the SSH agent config file in the following location: ```text %LOCALAPPDATA%/1Password/config/ssh/agent.toml ``` After you create the file, you may need to lock and then unlock 1Password for the agent config file to be recognized. **Linux:** 1. Open and unlock [1Password for Linux](https://1password.com/downloads/linux) and select any SSH key you want to add to the agent config file. If you don't have any SSH keys saved in 1Password yet, you can generate a new key in 1Password or import an existing key. 2. Select > **Configure for SSH Agent**. This will automatically create the SSH agent config file and open it in your default editor. You can then [modify the config file](#modify-the-ssh-agent-config-file) to add the SSH key. _[Create the SSH agent config file from the app]_ On Linux, 1Password will create the SSH agent config file in the following location: ```text ~/.config/1Password/ssh/agent.toml ``` 1Password also supports the `XDG_CONFIG_HOME` environment variable, if you have it configured. After you create the file, you may need to lock and then unlock 1Password for the agent config file to be recognized. ### From the terminal You can also choose to create the SSH agent config file yourself from the terminal. The file won't include any entries for your SSH keys — including any keys in your default Personal, Private, or Employee vault(s) — until you add them. When you create the file at the specified path, 1Password will detect it and override the default agent behavior, even if the agent config file is empty. Make sure to [modify the agent config file](#modify-the-ssh-agent-config-file) after you create it, to add any SSH keys items you need from any of your vaults or accounts. You can create the SSH agent config file on your machine at the specified path: **Mac:** On macOS, 1Password will look for the SSH agent config file at: ```text ~/.config/1Password/ssh/agent.toml ``` If you have the `XDG_CONFIG_HOME` environment variable configured, 1Password will check the following path first: ```text $XDG_CONFIG_HOME/1Password/ssh/agent.toml ``` **Windows:** On Windows, 1Password will look for the SSH agent config file at: ```text %LOCALAPPDATA%/1Password/config/ssh/agent.toml ``` **Linux:** On Linux, 1Password will look for the SSH agent config file at: ```text ~/.config/1Password/ssh/agent.toml ``` If you have the `XDG_CONFIG_HOME` environment variable configured, 1Password will check the following path first: ```text $XDG_CONFIG_HOME/1Password/ssh/agent.toml ``` ## Modify the SSH agent config file You can make your SSH keys available to the SSH agent by adding `[[ssh-keys]]` sections to the agent config file for any combination of individual keys, vaults, and accounts you have access to in 1Password, including shared and custom vaults. Your `[[ssh-keys]]` entries can be as specific or as broad in scope as you'd like, where you'll use at least one or more of the following key-value pairs to act like a series of queries on your SSH key items: - item: "The item name or ID" - vault: "The vault name or ID" - account: "The account name sign-in address or ID" These key-value pairs work like `WHERE`/`AND` clauses and operators, where the more data you include, the more specific your query becomes. If the SSH agent finds more than one key match per entry, the keys will be added in ascending order according to when the item was created (from the oldest to the most recent). To control the exact order, you can add additional `[[ssh-keys]]` sections to the agent config file. Before you modify the agent config file, make sure you're familiar with the [file syntax and structure](#file-syntax-and-structure), to ensure the SSH agent behaves as you expect it to. You don't need to restart the SSH agent each time you edit the agent config file. Your saved changes will be immediately available to the agent. ### Add individual keys You can add an `[[ssh-keys]]` section for an individual SSH key by including an `item` key-value pair in the entry. Include additional key-value pairs if you want to further specify which vault or account the SSH key is in. For example: ```toml title=agent.toml # Add my Git authentication key from my Work vault [[ssh-keys]] item = "Git Authentication Key" # Then add my Git signing key from my Work vault [[ssh-keys]] item = "Git Signing Key" vault = "Work" account = "ACME, Inc." ``` ### Add all keys in a vault You can add an `[[ssh-keys]]` section for all the SSH keys in a vault by including the `vault` key-value pair in the entry. You can include an `account` key-value if you want to specify which 1Password account the key is in, but don't include an `item` key-value pair or only that item will be added. For example: ```toml title=agent.toml # Add all keys from my Work vault [[ssh-keys]] vault = "Work" # Then add all keys from the Private vault in my family account [[ssh-keys]] vault = "Private" account = "Wendy Appleseed's Family" ``` If you add or remove SSH keys from the vault, access to the keys will be added to, or removed from, the SSH agent without needing to modify the agent config file later. ### Add all keys in an account You can add an `[[ssh-keys]]` section for all the SSH keys in a 1Password account by including the `account` key-value pair in the entry. Don't include the `item` or `vault` key-value pairs or you'll only add SSH keys for that item or vault. For example: ```toml title=agent.toml # Add all keys from my family account [[ssh-keys]] account = "Wendy Appleseed's Family" # Then add all keys from my work account [[ssh-keys]] account = "ACME, Inc." ``` Instead of the account name, you can also use the [sign-in address](https://support.1password.com/1password-glossary#sign-in-address) as the `account` value (sign-in addresses can include `https://` at the start, but it's not required). For example: ```toml title=agent.toml # Add all keys from my family account [[ssh-keys]] account = "my.1password.com" # Then add all keys from my work account [[ssh-keys]] account = "https://acme.1password.com" ``` If you add or remove SSH keys from the account, access to the keys will be added to, or removed from, the SSH agent without needing to modify the agent config file later. ### Filter keys You can use the `[[ssh-keys]]` entries as filters in the agent config file to progressively add keys for the SSH agent to access in your preferred order. When you have multiple 1Password accounts, like a work account and a family account, you can progressively filter the `[[ssh-keys]]` entries down by 1Password account. If you have any specific items or vaults that you want the SSH agent to offer to servers first, you can include those as well. For example: ```toml title=agent.toml # Add my Git signing key from my Work vault [[ssh-keys]] item = "Git Signing Key" vault = "Work" account = "ACME, Inc." # Then add all keys from the Private vault in my family account [[ssh-keys]] vault = "Private" account = "Wendy Appleseed's Family" # Then add all keys from the Private vault in my work account [[ssh-keys]] vault = "Private" account = "ACME, Inc." # Then add all remaining keys from any vault in my family account [[ssh-keys]] account = "Wendy Appleseed's Family" ``` ### Use IDs as values Using the name of an item, vault, or account in the agent config file makes it easier to identify what the entry is for. However, you might choose to use an ID in place of a name if: - **You don't want your item, vault, or account names stored in plaintext on disk.** [This metadata is encrypted](https://support.1password.com/1password-privacy#data-saved-in-1password:~:text=Your%20metadata%20is%20private) by default in 1Password, but the agent config file on your device is unencrypted. - **You expect the name of an item, vault, or account to be updated periodically.** IDs are the most stable way to reference an item. An item's ID only changes if you move it to a different vault. An example entry with an item ID: ```toml title=agent.toml {3} # Add my signing key from my Private vault [[ssh-keys]] item = "hhaeohhhc7iksdbadbx5pxyb6m" ``` To find and copy an item ID, go to the [**Advanced** settings](onepassword://settings/advanced) in the 1Password app and turn on **Show debugging tools**. Find the item you want and select it, then select > **Copy UUID**. Then paste the UUID value in the config file entry. You can also [use 1Password CLI to find the IDs for your items, vaults, and accounts](/docs/cli/reference#unique-identifiers-ids). ## Remove the SSH agent config file If you no longer want to use the SSH agent configuration file, you can delete the file or move it to another location. The 1Password SSH agent will then use the [default configuration](#agent-configuration-options) again. ## Get help To get help or provide feedback, use the `#ssh-agent-config` channel on the [1Password Developers Slack workspace](https://developer.1password.com/joinslack). This channel is used as the primary means of communication about the agent config file and is where we'll post updates and help answer questions. Errors in the agent config file If there's an error in the agent config file, the SSH agent will stop running and will notify you of the error in the [Developer settings](onepassword://settings/developers) of the 1Password app. Make sure each entry [uses the correct syntax](#file-syntax-and-structure). If you don't see an error message in 1Password but you're seeing an authentication error in your SSH client or having trouble using the SSH agent, check the values from your key-value pairs. If you make any typos in an item, vault, or account name value, the SSH agent won't be able to make a key match. Entries without key matches are not considered errors and will be ignored. If you're not able to use a specific key with the SSH agent and it's in the agent config file with the correct syntax and values, you can also check that the SSH key hasn't been archived or deleted. Any archived or deleted SSH Key items will be ignored, even if you specify them by ID. To see the list of all keys the SSH agent can access, you can run the `ssh-add -l` command, with the `SSH_AUTH_SOCK` environment variable set to the agent socket path: **Mac:** ```sh SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ssh-add -l ``` **Windows:** ```sh ssh-add -l ``` **Linux:** ```sh SSH_AUTH_SOCK=~/.1password/agent.sock ssh-add -l ``` ## Learn more - [Get started with 1Password for SSH & Git](/docs/ssh/get-started/) - [Advanced use cases](/docs/ssh/agent/advanced/) - [Manage SSH keys](/docs/ssh/manage-keys#generate-an-ssh-key) - [SSH client compatibility](/docs/ssh/agent/compatibility/) - [About 1Password SSH Agent security](/docs/ssh/agent/security/) --- ## SSH agent forwarding with 1Password SSH agent forwarding lets you make SSH requests within a remote environment as if it were your local machine, like running Git commands and signing commits from a [cloud development environment](#cde) or [remote workstation](#remote-workstation). Instead of storing your private keys on the remote host, you can use SSH agent forwarding to forward your requests to your local 1Password SSH Agent. Then authorize the request with biometrics without your private keys ever leaving the local 1Password process. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) 4. [Set up the 1Password SSH Agent](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) and make sure it's running on your local machine. :::tip If you use Windows If you use a Windows computer, you can [set up the 1Password WSL integration](/docs/ssh/integrations/wsl) to authenticate SSH requests in your WSL instance from your Windows host. ::: ## About SSH agent forwarding When you enable agent forwarding for a remote host, every SSH request you make within the remote environment gets forwarded to the local 1Password process over the 1Password SSH Agent socket. You can authorize SSH requests locally using options you've set up in 1Password, like your fingerprint. Then your authorization gets forwarded back to the remote host without ever needing to provide your private key to the remote server. :::caution Make sure you only use SSH agent forwarding with trusted hosts. [Learn how to use SSH agent forwarding more securely.](#security) ::: ## Set up SSH agent forwarding {#set-up} SSH agent forwarding is turned off in OpenSSH by default. You can choose to turn it on for a [single session](#for-a-single-session) or for a [specific host](#for-a-specific-host). ### For a single session To turn on agent forwarding for a single session only, use the `-A` flag with the `ssh` command: ```shell ssh -A user@example.com ``` When you're connected to the remote host with agent forwarding turned on, the `SSH_AUTH_SOCK` environment variable on the remote host is automatically set. Data sent over this socket gets forwarded to the local 1Password socket. ```text user@example.com:~$ echo $SSH_AUTH_SOCK #code-result /tmp/ssh-XXXXNpdlnL/agent.151 ``` To check if agent forwarding is working, run the following command view a list of the SSH keys forwarded from 1Password to the remote host: ```text user@example.com:~$ ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` If you see your SSH key listed, try to run an SSH request from within the remote server: ```text user@example.com:~$ ssh -T git@github.com ``` The 1Password app on your local machine should prompt you to authorize the request. ### For a specific host If you want to set up SSH agent forwarding for a specific host all the time so you don't need to use the `-A` flag for each session, edit your `~/.ssh/config` file to include that host: ```text Host example.com ForwardAgent yes ``` ## SSH agent forwarding security {#security} ### Security considerations When you authorize your local terminal, IDE, or other SSH client to use an SSH key in an agent forwarding session, any new connection made within the remote environment using the same key is also authorized. If someone else were to gain access to the remote environment as the same OS user, they'd be able to use the SSH key to authenticate connections from the remote host for the duration of the session. However, any other SSH keys available in the remote environment still require your approval before they can be used. Unlike the standard OpenSSH agent, where every key in the agent can be used in the remote environment without additional authorization, the 1Password SSH Agent requires your approval for each SSH key before it can be used. An attempt to use one of those keys from the remote environment triggers a 1Password authorization prompt that needs to be authenticated, making agent forwarding more secure with 1Password than with the OpenSSH agent. ### Use agent forwarding more securely We recommend the following: - Only use agent forwarding when you need it and in environments that you trust are secure. - Set up agent forwarding on a [per-command basis](#for-a-single-session) or configure your `~/.ssh/config` file to allow agent forwarding [only with specific hosts](#for-a-specific-host). **Do not turn on SSH agent forwarding for all hosts by default.** ```text variant="bad" title="~/.ssh/config (bad 👎)" Host * ForwardAgent yes ``` We recommend that you always scope the `ForwardAgent yes` directive down to a specific host or domain you trust for agent forwarding. For example, to turn on agent forwarding for [Gitpod ](https://www.gitpod.io/): ```text variant="good" title="~/.ssh/config (good 👍)" Host *.gitpod.io ForwardAgent yes ``` ## Use case: Cloud Development Environment {#cde} If you use a local integrated development environment (IDE) to connect to a cloud development environment (CDE) and you want to pull, push, and sign remote Git commits, you can authenticate those commands through the local 1Password SSH Agent. For example, you might have an IDE desktop app on your local workstation that you use to authenticate into a cloud-based development environment. You want to use the the CDE workspace to access remote Git repositories and you need to be able to authenticate Git requests and sign commits. With SSH agent forwarding, you can authenticate SSH and Git commands from your CDE workspace in your IDE desktop app through the 1Password SSH Agent running on your local workstation. ### Set up SSH agent forwarding To set up SSH agent forwarding so you can authorize Git requests from your cloud development environment, [edit your SSH config file to add your CDE host](#for-a-specific-host). The remote development integration in your IDE should recognize this automatically. To check if agent forwarding is correctly set up, open a remote shell in your IDE then run the following command: ```shell ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` You should see a list of the SSH keys the agent can use for SSH requests. ### Use SSH for Git authentication If your CDE is set up to use HTTPS to authenticate with Git and you want to use SSH instead, run the following command to modify the remote Git configuration for the CDE: ```shell git config --global url."ssh://git@".insteadOf "https://" ``` Alternatively, you can add the command to your cloud development initialization (cloud-init) script or dotfiles. The next time you make a Git request from your CDE, 1Password should prompt you to authorize the request. For example: ```shell git fetch ``` If you only want to use SSH authentication going forward, you may want to revoke HTTPS write access to your repository. ### Set up Git commit signing {#git-commit-signing-cde} Your local `.gitconfig` file isn't automatically forwarded to your cloud development environment, so you'll need to modify the Git configuration in your CDE to set up remote Git commit signing. 1. Configure Git to use SSH for commit signing: ```shell git config --global gpg.format ssh ``` 2. Tell Git to always sign commits: ```shell git config --global commit.gpgsign true ``` 3. Set the SSH key you want to use to sign commits: ```shell git config --global user.signingkey <your SSH public key> ``` ### Authorization model {#authorization-model-cde} When you run an SSH or Git request in your cloud development environment that requires authorization, 1Password will prompt you to approve SSH key usage for the IDE that's connected to your CDE. If you approve the request, the entire IDE will be authorized to use that key. Any process running on the cloud development environment under the same OS user will also be authorized, which is a [security consideration](#security) to keep in mind. ## Use case: Remote workstation {#remote-workstation} If you have a remote workstation that you connect to over SSH, and you want to run SSH and Git requests from that workstation, you can authenticate those requests through the 1Password agents that runs on your local host. For example, you might have a desktop workstation at home that contains all your Git repositories. You want to work on the go, so you use your laptop to connect to your remote workstation over SSH so you can work in your Git repos. With SSH agent forwarding, you can authenticate SSH and Git commands from your remote workstation through the 1Password SSH Agent running on your local laptop. ### Set up SSH agent forwarding To set up SSH agent forwarding so you can authorize SSH and Git requests from your remote workstation, [edit the SSH config file](#for-a-specific-host) on your local host to allow agent forwarding with your remote workstation. To check if agent forwarding is correctly set up, connect to your remote workstation then run the following command: ```shell ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` You should see a list of the SSH keys the agent can use for SSH requests. ### Modify the `IdentityAgent` configuration on the remote workstation If your remote workstation also has the 1Password SSH Agent installed, you'll want to make sure that Git and SSH use the forwarded socket from your local host instead of the agent socket for the 1Password app installed on the remote workstation. The `IdentityAgent` takes precedence over the `SSH_AUTH_SOCK` environment variable, so you may want to modify the `~/.ssh/config` file for your remote workstation so the `IdentityAgent` setting is only applied if you're not in an SSH shell. ```text Match host * exec "test -z $SSH_TTY" IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock" ``` Then any Git or SSH command executed from an SSH shell on the remote workstation will use the forwarded `SSH_AUTH_SOCK` for authentication and 1Password should prompt you to authorize SSH requests from your local host. This change won't affect how the 1Password SSH Agent runs when you use the workstation locally instead of accessing it remotely. The `IdentityAgent` setting will be applied as usual to use the SSH agent running on the workstation. ### Set up Git commit signing Your local `.gitconfig` file isn't automatically forwarded to your remote workstation, so the remote Git configuration will be used by default. If you've configured [Git commit signing with 1Password](/docs/ssh/git-commit-signing) on the remote workstation using the same SSH key you use on your local host, you shouldn't need make any changes to your setup. If the `op-ssh-sign` signing program finds that both the `SSH_AUTH_SOCK` and the `SSH_TTY` environment variables are set, it will automatically adapt to use the forwarded socket from your local host instead of the 1Password socket from your remote workstation. ### Authorization model {#authorization-model-remote-workstation} When you run an SSH or Git request from a remote shell or remotely connected IDE that requires authorization, 1Password will prompt you to approve SSH key usage for the terminal or IDE you use to connect to the remote workstation. If you approve the request, the entire app will be authorized to use this key. Any process running on the remote workstation under the same OS user will also be authorized, which is a [security consideration](#security) to keep in mind. ## Troubleshooting If you're having trouble using agent forwarding with the 1Password SSH Agent, there are a few things you should check. ### Check if the `SSH_AUTH_SOCK` environment variable is set Run `echo $SSH_AUTH_SOCK` in the terminal to make sure the environment variable is set on your server. ```text user@example.com:~$ echo $SSH_AUTH_SOCK #code-result /tmp/ssh-XXXXNpdlnL/agent.151 ``` If the variable isn't set, SSH agent forwarding won't work. Make sure [the 1Password SSH Agent is turned on](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) and that you've [configured your SSH client to use the agent for authentication](/docs/ssh/get-started#step-4-configure-your-ssh-or-git-client). ### Check if the SSH agent can access the correct SSH key Run `ssh-add -l` in the terminal to see a list of the SSH keys forwarded from 1Password to the remote host: ```text user@example.com:~$ ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` If you don't see your SSH key listed, make sure the key is [eligible to use with the 1Password SSH Agent](/docs/ssh/agent#eligible-keys) and that it's [saved in a vault the SSH agent is configured to use](/docs/ssh/agent#configuration). ### Check if agent forwarding is allowed on the server To use agent forwarding with a remote server, the `AllowAgentForwarding` option must be set to `Yes` in the [`sshd_config` file](https://man.openbsd.org/sshd_config) for the server. --- ## 1Password SSH agent The 1Password SSH agent uses the SSH keys you have saved in 1Password to seamlessly integrate with your Git and SSH workflows. It authenticates your Git and SSH clients without those clients ever being able to read your private key. In fact, your private key never even leaves the 1Password app. The SSH agent works with the SSH keys stored in 1Password, but never without your consent. Only SSH clients you explicitly authorize will be able to use your SSH keys until 1Password locks. Learn how to [turn on the 1Password SSH agent](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) and [configure your SSH clients](/docs/ssh/get-started#step-4-configure-your-ssh-or-git-client). ## Requirements **Mac:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Mac.](https://1password.com/downloads/mac) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. **Windows:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Windows.](https://1password.com/downloads/windows) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. **Linux:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Linux.](https://1password.com/downloads/linux) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. :::warning[caution] The 1Password SSH agent doesn't work with [Flatpak ](https://flatpak.org/) or Snap Store installations of 1Password. To use the SSH agent, choose a different method to [install 1Password for Linux](https://support.1password.com/install-linux/). ::: :::tip For the best experience when using the 1Password SSH agent, you can configure [Touch ID](https://support.1password.com/touch-id-mac/), [Apple Watch](https://support.1password.com/apple-watch-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or [system authentication](https://support.1password.com/system-authentication-linux/) to unlock 1Password and authenticate SSH key requests. ::: ## Configuration By default, the 1Password SSH agent will make every [eligible key](/docs/ssh/agent#eligible-keys) in the built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault of your 1Password accounts available to offer to SSH servers. This configuration is automatically set up when you [turn on the SSH agent](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent). If you need to use the SSH agent with keys saved in shared or custom vaults, you can create and customize an [SSH agent config file](/docs/ssh/agent/config/) (`~/.config/1Password/ssh/agent.toml`) to override the default agent configuration. If you have more than six SSH keys available in the agent, you can edit your SSH config file or use [SSH Bookmarks](/docs/ssh/bookmarks/) to match your keys to specific hosts. This will help you avoid authentication failures with OpenSSH servers that limit the number of connection attempts. Learn more about the [SSH server six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). ## Eligible keys For the 1Password SSH agent to work with your SSH keys, your 1Password SSH key items must meet the following requirements. They must be: - [Generated](/docs/ssh/manage-keys#generate-an-ssh-key) or [imported](/docs/ssh/manage-keys#import-an-ssh-key) using the `SSH Key` item type (which supports [`Ed25519` or `RSA`](/docs/ssh/manage-keys#supported-ssh-key-types) key types). - Stored in the vaults [the SSH agent is configured to use](#configuration) in 1Password. By default, this is the [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault of any 1Password account you're signed in to. - Active items (not archived or deleted). Any key meeting these requirements will automatically be available in the SSH agent for authentication. You will still be required to explicitly [authorize any request](/docs/ssh/agent/security#authorization-model) an SSH client makes to use your keys. To see a list of all keys that the agent has available, [set the `SSH_AUTH_SOCK` environment variable](/docs/ssh/get-started#step-4-configure-your-ssh-or-git-client) (Mac and Linux only) and run: ```shell ssh-add -l ``` --- ## About 1Password SSH Agent security The 1Password SSH Agent allows you to securely authenticate all your Git and SSH commands from 1Password. Your private keys never leave 1Password, are never stored locally, and are never used without your consent. ## Differences with the OpenSSH agent The standard OpenSSH agent (`ssh-agent`) that comes preinstalled on most operating systems requires you to add keys to the agent (`ssh-add`) every time it launches. After you've added your SSH keys, any process can use any key that the OpenSSH agent is managing. It's then up to you to remove those keys when they're not needed anymore. The 1Password SSH Agent uses a different approach and asks for your consent before an SSH client or terminal session can use your key. Because of this, there's no concept of adding or removing keys like with the OpenSSH agent. When you [turn on the SSH agent](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) from the 1Password preferences or settings, every [eligible key](/docs/ssh/agent#eligible-keys) saved in 1Password becomes available to use for SSH, but your private keys will never be used without your consent. ## Authorization model {#authorization-model} ### About the authorization model The authorization model for the 1Password SSH Agent is built on the idea that you should be able to control which processes are allowed to use which private keys. When an SSH client or terminal session on your system makes a request through the SSH agent to use one of your keys, 1Password will ask if you want to approve the request. The authorization prompt indicates which process is requesting permission to use which SSH key. After you approve the request, a session is established between the key and the process the SSH command was run from (a process can be a terminal window or tab, an IDE, or a GUI application, like a Git or SFTP client). Any subsequent SSH commands run in that process can use your key without further approval until 1Password locks or quits, or for the amount of time set in the [options you've configured](#authorization-options). For example, if you authorize a `git pull` command from the terminal for one of your SSH keys, 1Password won't prompt you to approve your following `git push` because the session is already approved. When 1Password is locked, the SSH agent continues to run in the background and will prompt you if an SSH client tries to use one of your keys. If you've already authorized the client to use your key for a set amount of time (for example, four hours) instead of when 1Password locks, your approval will still be in the agent's memory and you'll only be prompted to unlock 1Password. The SSH agent doesn't keep your private keys in memory when 1Password is locked, only your authorization, so the app needs to be unlocked for the agent to access your private keys. ### Approving SSH key requests When the SSH agent requires your approval to use one of your keys, 1Password will show you an authorization prompt that lets you approve the request using options like Touch ID, Windows Hello, your 1Password account password, and more. The authorization method will vary depending on your device, operating system version, 1Password settings, and other factors, so the prompt will indicate how you can authorize the request. You'll also have the option to deny any request. If the SSH key you're approving belongs to an account that uses [1Password Unlock with SSO](https://support.1password.com/sso-get-started/), you may be redirected to the sign-in page for your identity provider. You'll then need to sign in using the credentials for your provider account to authorize the request. ### Authorization options The authorization model for the 1Password SSH Agent allows for some flexibility, so you can set it up to best suit your needs at any given time. You'll always be asked to authorize the use of each private key, but you can adjust options like how long an SSH agent session lasts (how long the agent remembers your key approval). This could be until 1Password locks or quits, or until a set amount of time has passed. You can also choose what usage you're approving for each key, which determines when the SSH agent will ask you to approve requests. With all options, your authorization grants access to an SSH key within that agent session, or until the application or terminal session quits. Usage options you can choose include: - **Per key, per application** (default): When you approve an SSH key request, you authorize a specific application (including all of it's subprocesses) to use a specific SSH key. - **Per key, per application, per terminal session**: When you approve an SSH key request, you authorize a specific application (including all of it's subprocesses) to use a specific SSH key, but with an additional restrictions. If the application is a terminal emulator or an IDE with a built-in terminal, your authorization only applies to a specific tab. Each new terminal tab in that application requires separate approval to use that key. - **Per key, once for every process running on the user’s system**: You can see this option on a per-request basis for a specific SSH key by selecting the **Approve for all applications** checkbox on the authorization prompt. This temporarily authorizes all processes running under the current OS user to use that key for the duration of the agent session. Access is only restricted by file permissions on the agent socket or named pipe. This option doesn't affect your other settings. [Learn how to adjust the authorization options for the 1Password SSH Agent.](/docs/ssh/get-started#adjust-your-authorization-options) ## Suppressing background requests It’s very common for IDEs and Git GUI clients to periodically run `git fetch` in the background on currently open repositories. This feature is often enabled by default and may result in unexpected authorization prompts from 1Password, especially if you're unaware of an application's auto-fetch behavior. 1Password helps to suppress prompts if it detects that the app or window the request originated from is not in the foreground. The 1Password icon in your device's menu bar, taskbar, or system tray will display an indicator dot when a prompt has been suppressed. If you need to access the prompt, select the 1Password icon and select **SSH request waiting**. The authorization prompt will be brought to the foreground. ## Local storage When you turn on the SSH agent, the 1Password app will store an unencrypted copy of the **public keys** of all your [eligible SSH keys](/docs/ssh/agent#eligible-keys) on disk. Storing your public keys allows the SSH authorization prompt to be shown even when 1Password is locked. If you turn on "Display key names when authorizing connections" for the SSH agent, the 1Password app will also store an unencrypted copy of your SSH key **item titles** on disk. Displaying SSH key names is optional and this setting is turned off by default. This setting can be turned on or off in the 1Password app. If the setting is turned off, your SSH key names will not be stored. The authorization prompt will instead show a truncated public key fingerprint for identification. --- ## Troubleshooting ## Create an SSH agent diagnostics report If you're experiencing issues with how the SSH agent handles your SSH requests, you can send us an SSH diagnostics report so we can help resolve the problem. You must use a [beta](https://support.1password.com/betas/) or nightly release of the 1Password app to create an SSH diagnostics report. ### Step 1: Set up SSH diagnostics recording To start recording SSH diagnostics, navigate to the 1Password data directory: **Mac:** ```text ~/Library/Group Containers/2BUA8C4S2C.com.1password/Library/Application Support/1Password/Data ``` **Windows:** ```text %LOCALAPPDATA%\1Password ``` **Linux:** ```text ~/.config/1Password ``` From this location, create a new subdirectory called `ssh-diagnostics`. SSH diagnostics recording is now enabled. ### Step 2: Run some SSH requests Run a few SSH requests using your preferred setup and tools to reproduce the issue you're having. Each SSH request you run will be logged as a pair of JSON files in the `ssh-diagnostics` directory. ### Step 3: Create a ZIP file of your `ssh-diagnostics` directory After you've recorded a few SSH requests that demonstrate the issue, create a ZIP file of your `ssh-diagnostics` directory. To stop recording, delete the `ssh-diagnostics` directory. ### Step 4: Remove personally identifiable information (PII) from the diagnostics files The files generated during the SSH diagnostics recording may contain PII, like your OS username, Git repo names, and SSH hosts. The 1Password app attempts to redact as much of this data as possible and you'll see things like `<redacted:username>`, `<redacted:git-repo>`, and `<redacted:host>` in the generated JSON files. However, there could still be some PII contained in your diagnostics files. Make sure to check for any information you don't want to include, like a company name that appears as part of a path, and redact it. Then recreate your ZIP file. --- ## Manage SSH Bookmarks in 1Password (beta) SSH Bookmarks in 1Password allow you to: - Connect to SSH hosts directly from 1Password, without manually entering commands in the terminal. - Match your SSH keys to specific hosts to make sure the correct key is used for each connection. - Avoid [server key limitations](/docs/ssh/agent/advanced#ssh-server-six-key-limit) when managing multiple SSH keys. You can add bookmarks from the [SSH activity log](https://support.1password.com/developer#ssh-activity-log) or by adding `ssh://` URLs to your SSH Key items. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) 4. [Set up the 1Password SSH Agent.](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) 5. [Turn on 1Password Developer.](https://support.1password.com/developer#turn-on-1password-developer) ## Manage your SSH Bookmarks You can use and manage SSH Bookmarks for hosts that use keys [available to the 1Password SSH agent](/docs/ssh/agent#eligible-keys). If you're signed in to [multiple accounts](https://support.1password.com/multiple-accounts/) in the 1Password desktop app, make sure to unlock the accounts where you've stored the keys for your SSH hosts. ### Create a bookmark Create bookmarks for your frequently used SSH hosts from the [SSH activity log](#from-the-activity-log) or in an [SSH Key item](#in-an-ssh-key-item). #### From the activity log The quickest way to create a bookmark is to use the Bookmark option in the [SSH activity log](https://support.1password.com/developer#ssh-activity-log). You'll see a **Bookmark** button next to any `ssh` commands you've run from the terminal (like `ssh user@hostname`). 1. Open the 1Password desktop app. Select **Developer** in the sidebar, then select **View SSH agent**. If you don't see Developer in the sidebar, [turn on 1Password Developer](https://support.1password.com/developer#turn-on-1password-developer). 2. Navigate to the Activity section and find the entry for the SSH host you want to bookmark. 3. Select **Bookmark** in the Actions column. 1Password will add the SSH host URL to the associated SSH Key item, then add the bookmark to the [Bookmarks](https://support.1password.com/developer#ssh-bookmarks) section of the SSH Agent developer page. #### In an SSH Key item If you want to create a bookmark for an SSH host that you haven't connected to recently, you can manually add a custom URL field to an SSH Key item. In 1Password, find the SSH Key item for the host you want to bookmark, then edit the item to add a [custom field](https://support.1password.com/custom-fields#add-a-custom-field) with the SSH host URL (a field label isn't required). The bookmark will be added to the [Bookmarks](https://support.1password.com/developer#ssh-bookmarks) section of the SSH Agent developer page. SSH host URLs must start with `ssh://` and can use the hostname or IP address of the SSH host. If you've defined a `Host` block in your `~/.ssh/config` file with a custom alias (for example, `Host my-host-alias`), you can also bookmark the alias instead of the actual hostname or IP address. Examples of different types of bookmarks: - **Hostname**: `ssh://user@example.org`, `ssh://test-server.example.com` - **IP address**: `ssh://admin@192.0.2.255`, (IPv4), `ssh://user@2001:DB8:a8b0:5678::200c` (IPv6) - **Host alias**: `ssh://my-host-alias` ### Connect to a bookmarked host Connect to any of your bookmarked SSH hosts directly from the [Bookmarks](https://support.1password.com/developer#ssh-bookmarks) section of the SSH Agent developer page. To use a bookmark from the list, select **Connect**. 1Password will launch the terminal, which initiates a connection to the SSH host. Then [authorize the connection](https://developer.1password.com/docs/ssh/get-started#step-6-authorize-the-ssh-request), if prompted. 1Password uses the [terminal application](#terminal-for-ssh-connections) set for SSH URLs to connect to the host. ### Edit a bookmark From the [Bookmarks](https://support.1password.com/developer#ssh-bookmarks) section of the SSH Agent developer page: 1. Select > **View SSH Key item** in the bookmark's Actions menu. 2. Select **Edit**, then update the host URL field. 3. Save your changes. Your saved changes will automatically update in your Bookmarks list. ### Remove a bookmark From the [Bookmarks](https://support.1password.com/developer#ssh-bookmarks) section of the SSH Agent page, select > **Remove bookmark** in the bookmark's Actions menu. You can also remove a bookmark by editing the SSH Key item. Remove the SSH host URL from the item, or delete the item if you no longer need the SSH key. Using either method removes an SSH Bookmark from your Bookmarks list, the SSH Key item, and the [1Password SSH configuration file](#ssh-bookmarks-config-file), if you turned on that feature. ## SSH Bookmarks config file 1Password can automatically manage an SSH config file (`~/.ssh/1Password/config`) that matches bookmarked SSH hosts with the corresponding SSH key. You can include this file in your main SSH config file (`~/.ssh/config`). This also prevents you from running into the [six-key server limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). Note that generating SSH configuration files will store your unencrypted SSH host URLs and SSH public keys for your bookmarks on disk. Your private keys will remain safe in 1Password. ### Generate the 1Password config file This feature is turned off by default, so you'll need to turn on the setting in 1Password: 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). 2. Go to the Advanced section for the SSH Agent (you may need to select the section to expand it). 3. Select **Generate SSH config files from 1Password SSH bookmarks**. If you see a message that says "Managed by administrator", the setting is managed by your team's [app usage policy](https://support.1password.com/team-policies#app-usage). Contact your team administrator to learn more. 1Password will generate a directory at `~/.ssh/1Password/` that includes: - `~/.ssh/1Password/config` file: An SSH configuration file that maps SSH hosts to their corresponding keys. - `*.pub` files: Individual public key files for each bookmarked host, named using the SSH key's public fingerprint. ### Use the configuration file To start using the 1Password configuration file, you'll need to include it in your main SSH config file. Add the following line to the top of your `~/.ssh/config` file: ```toml Include ~/.ssh/1Password/config ``` Then save your changes to the file. 1Password manages changes to the `~/.ssh/1Password/config` file. Any time you create, edit, or remove an SSH Bookmark, 1Password automatically updates the configuration file. If you want to override any of the rules from the 1Password configuration file, you can do so by editing your SSH configuration file. Copy the relevant `Match Host` block from the 1Password-generated `~/.ssh/1Password/config` file into your `~/.ssh/config` file. Then edit the configuration values in the block to your preferred values. If you turn off the setting to generate configuration files, 1Password will remove the `~/.ssh/1Password` directory and all generated files. :::caution Do not manually edit the 1Password-generated files Manual edits made to the 1Password-generated files won't be saved. If you need to make changes, [edit your SSH Bookmarks](#edit-a-bookmark) in 1Password or make the changes in your main `~/.ssh/config` file. ::: ## Terminal for SSH connections 1Password will use your system's default terminal application to launch SSH connections without additional setup, or you can choose your preferred terminal option in the settings. **Mac:** #### Choose a terminal option for SSH Bookmarks {#choose-terminal-mac} 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). 2. Go to the Advanced section for the SSH Agent and locate the **Open SSH URLs with** setting. 3. Select your preferred terminal application from the available options. **Windows:** #### Choose a terminal option for SSH Bookmarks {#choose-terminal-windows} 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). 2. Go to the Advanced section for the SSH Agent and locate the **Open SSH URLs with** setting. 3. Select the option you want 1Password to use to open SSH connections: Windows Terminal or a [custom terminal command](#set-custom-command-windows). #### Set a custom terminal command {#set-custom-command-windows} The custom terminal command option allows you to provide your own shell command to open `ssh://` URLs. Terminal commands are executed using the `cmd.exe /c start` process and can only contain simple command-line arguments. For more complex arguments that use environment variables or interpolation, you can create a script file and use the script's file path in your command. A basic command structure could include the terminal application, with any options and flags you want to use to specify the terminal's behavior, followed by the SSH command and [URL option(s)](#url-options-windows). For example, if you want 1Password to use the Windows Terminal to open an SSH URL in a maximized window with a vertical, split-pane, you could use a command like: ``` wt.exe --maximized split-pane -V ssh %s ``` If your terminal app isn't in your `PATH`, use the full path of the app in your command. For example: ``` "C:\Program Files (x86)\My Terminal App\MyTerminalApp.exe" ssh %s ``` For more complex arguments, you can create a custom script and use the full path of the script in your command. For example: ``` "C:\Scripts\MyScript.ps1" %s ``` :::info For more examples of Windows command-line arguments, see [Microsoft's documentation. ](https://learn.microsoft.com/en-us/windows/terminal/command-line-arguments?tabs=windows) ::: ##### SSH URL options and variables {#url-options-windows} You can use one or more of the following options in your command to reference all or part of the SSH URL in your bookmark: - `%s`: the full SSH URL in your bookmark (for example: `ssh://admin@example.com:9999`) - `%u`: the user (`admin`) - `%h`: the host (`example.com`) - `%p`: the port (`9999`) If you want 1Password to use the full SSH URL syntax from your bookmark, use the `%s` option in your custom command: ``` my-command %s ``` If your SSH client doesn't support the SSH URL syntax, use the `%u` and `%h` options to pass the host and user variables separately when 1Password invokes your custom command: ``` my-command --user %u --host %h --port %p ``` The `--port %p` variable is optional. You don't need to include port information in your bookmark or custom command unless you need to use a port other than the default SSH port (`22`). If you don't want 1Password to replace an SSH URL option with a variable, add a backslash (`\`) before the option to escape it so it's treated as a literal string. For example: ``` my-command \%s ``` **Linux:** #### Choose a terminal option for SSH Bookmarks {#choose-terminal-linux} 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). 2. Go to the Advanced section for the SSH Agent and locate the **Open SSH URLs with** setting. 3. Select the option you want 1Password to use to open SSH connections: your preferred terminal application from the available options, a [custom terminal command](#set-custom-command-linux), or [xdg-open](#configure-xdg-open). If you want 1Password to handle your bookmarks separately from the rest of your system, you can choose your preferred terminal or a custom command in 1Password and configure `xdg-open` for your system. #### Set a custom terminal command {#set-custom-command-linux} The custom terminal command option allows you to provide your own shell command to open `ssh://` URLs. Terminal commands are executed using the `systemd-run` process and can only contain [simple command-line arguments. ](https://linux.die.net/man/1/bash) For more complex arguments that use environment variables or interpolation, you can create a script file and use the script's file path in your command. A basic command structure could include the terminal application, with any options and flags you want to use to specify the terminal's behavior, followed by the SSH command and [URL option(s)](#url-options-linux). For example, if you want 1Password to use the WezTerm terminal app to open an SSH URL in a new `tmux` session on a remote server, you could use a custom command like: ``` wezterm -e ssh %s tmux new -A ``` If your terminal app isn't in your `PATH`, use the full path of the app in your command. For example: ``` /home/my-apps/my-terminal-app ssh %s ``` For more complex arguments, you can create a custom script and use the full path of the script in your command. For example: ``` /home/user/scripts/my-custom-script.sh %s ``` ##### SSH URL options and variables {#url-options-linux} You can use one or more of the following options in your command to reference all or part of the SSH URL in your bookmark: - `%s`: the full SSH URL in your bookmark (for example: `ssh://admin@example.com:9999`) - `%u`: the user (`admin`) - `%h`: the host (`example.com`) - `%p`: the port (`9999`) If you want 1Password to use the full SSH URL syntax from your bookmark, use the `%s` option in your custom command: ``` my-command %s ``` If your SSH client doesn't support the SSH URL syntax, use the `%u` and `%h` options to pass the host and user variables separately when 1Password invokes your custom command: ``` my-command --user %u --host %h --port %p ``` The `--port %p` variable is optional. You don't need to include port information in your bookmark or custom command unless you need to use a port other than the default SSH port (`22`). If you don't want 1Password to replace an SSH URL option with a variable, add a backslash (`\`) before the option to escape it so it's treated as a literal string. For example: ``` my-command \%s ``` #### Configure `xdg-open` You can use `xdg-open` to open `ssh://` URLs with the application that registers the `x-scheme-handler/ssh` MIME type. To customize how `xdg-open` launches `ssh://` URLs, you can create a `.desktop` file: 1. Create a file called `1password-ssh-handler.desktop` in `~/.local/share/applications` with the following content: ```file {3} title=1password-ssh-handler.desktop [Desktop Entry] Name=1Password SSH Handler Exec=gnome-terminal -- ssh %u Terminal=false Type=Application MimeType=x-scheme-handler/ssh; ``` You can edit the `Exec` command to use your preferred terminal. 2. Run the following command in your terminal to register the SSH handler: ```shell update-desktop-database ~/.local/share/applications ``` ## Learn more - [Advanced use cases](/docs/ssh/agent/advanced/) - [SSH agent config file](/docs/ssh/agent/config/) - [Sign Git commits with SSH](/docs/ssh/git-commit-signing/) --- ## Get started with 1Password for SSH You can use 1Password to generate an SSH key and autofill your public key to your favorite Git platform. Then, set up the 1Password SSH agent and configure your SSH or Git client so you can use the 1Password SSH agent to authenticate your Git and SSH workflow. The following examples use GitHub to illustrate the SSH workflow from start to finish, but you can modify the steps to use with your favorite Git or cloud platform. ## Requirements **Mac:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Mac.](https://1password.com/downloads/mac) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. **Windows:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Windows.](https://1password.com/downloads/windows) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. **Linux:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Linux.](https://1password.com/downloads/linux) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. :::warning[caution] The 1Password SSH agent doesn't work with [Flatpak ](https://flatpak.org/) or Snap Store installations of 1Password. To use the SSH agent, choose a different method to [install 1Password for Linux](https://support.1password.com/install-linux/). ::: :::tip For the best experience when using the 1Password SSH agent, you can configure [Touch ID](https://support.1password.com/touch-id-mac/), [Apple Watch](https://support.1password.com/apple-watch-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or [system authentication](https://support.1password.com/system-authentication-linux/) to unlock 1Password and authenticate SSH key requests. ::: ## Step 1: Generate an SSH key 1. Open and unlock the 1Password app, then navigate to your **Personal**, **Private**, or **Employee** vault. The name of this vault varies depending on your account type. 2. Select **New Item** > **SSH Key**. 3. Select **Add Private Key** > **Generate New Key**. 4. Select an SSH key type: [Ed25519 or RSA](/docs/ssh/manage-keys#supported-ssh-key-types), then select **Generate**. 5. When you're done, select **Save**. 1Password will generate your SSH key, which includes the private key, public key, and its fingerprint. _[Generating a new SSH Key item with the Ed25519 key type selected.]_ Learn more about [generating or importing SSH keys](/docs/ssh/manage-keys/) and [which SSH keys you can use with the 1Password SSH agent](/docs/ssh/agent#eligible-keys). ## Step 2: Upload your public key After you generate your SSH key, you can add the public key to your GitHub account. Visit the [GitHub SSH key settings page](https://github.com/settings/ssh/new) upload your public key using the 1Password browser extension or desktop app. **Browser extension:** 1. Select the **Title** or **Key** field on the GitHub settings page. If 1Password doesn't show a list of suggested items, select the 1Password icon in the field. 2. Select the GitHub SSH key you just created. 1Password will automatically fill the public key and title in the corresponding fields. 3. Select **Add SSH Key** on the settings page to save the key in your GitHub account. Your SSH key can now be used to authenticate with GitHub. For examples using other Git or cloud platforms, see [Autofill public keys](/docs/ssh/public-key-autofill/). _[The GitHub SSH key settings page in a browser, with the Key field selected on the page and the GitHub SSH key item selected in the 1Password popup.]_ **Desktop apps:** 1. Navigate to the GitHub SSH key you just created in 1Password and select it. 2. Copy your public key from the item details, then paste it into the **Key** field on the GitHub settings page. You can also use Quick Access to find and copy your public key. 3. Then select **Add SSH Key** on the settings page to save the key in your GitHub account. Your SSH key can now be used to authenticate with GitHub. For examples using other Git or cloud platforms, see [Autofill public keys](/docs/ssh/public-key-autofill/). _[A GitHub SSH Key item selected in the 1Password desktop app, with the public key field selected and ready to copy.]_ ## Step 3: Turn on the 1Password SSH agent The 1Password desktop app includes an SSH agent that, when turned on, runs in the background to handle authentication for your SSH clients. Follow these steps to turn on the SSH agent: **Mac:** 1. Open the 1Password app and select **1Password** > **Settings** from the menu bar, then select **Developer**. 2. Select **Set Up SSH Agent**, then choose whether you want to display SSH key names when you authorize connections. 3. (Optional) [Adjust the authorization options](#adjust-your-authorization-options) for when and how often the SSH agent will ask you to approve SSH requests. _[The SSH agent developer settings in the 1Password desktop app, with both checkboxes selected and a badge at the top that shows the agent is running.]_ If you previously turned off the SSH agent and would like to turn it back on, select the checkbox to **Use the SSH agent**. When you choose to display SSH key names when authorizing connections, it's easier for you to identify which key 1Password is requesting access to when authenticating a request from an SSH client. To display key names in authorization prompts, 1Password needs to [save the titles of your SSH Key items in local storage](/docs/ssh/agent/security#local-storage). To turn off this feature, deselect the checkbox to **Display key names when authorizing connections** in the Security section. To make sure the SSH agent keeps running, even when the 1Password app is closed: 1. Open the 1Password app and select **1Password** > **Settings** from the menu bar, then select **General**. 2. Select the checkboxes to **Keep 1Password in the menu bar** and **Start at login**. _[The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running.]_ **Windows:** :::warning[caution] The 1Password SSH agent only works with SSH clients that support [Microsoft OpenSSH](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview). For more information, see [SSH client compatibility](/docs/ssh/agent/compatibility/). ::: #### Check if the OpenSSH Authentication Agent service is installed and running Before you can turn on the SSH agent in 1Password, you'll need to check if the OpenSSH Authentication Agent service is installed: 1. Go to **Services** > **OpenSSH Authentication Agent** (press <kbd>Win</kbd> + <kbd>R</kbd> on your keyboard to open the Run window, type `services.msc` and press <kbd>Enter</kbd> or select **OK**). 2. Look for the **OpenSSH Authentication Agent** in the list of services. If you don't see the OpenSSH Authentication Agent in the list, skip ahead to the steps to [turn on the SSH agent in 1Password](/docs/ssh/get-started#turn-on-the-ssh-agent-in-1password). If you do see the OpenSSH Authentication Agent in the list, continue with these steps to disable it from startup and make sure it's not running: 3. Select **OpenSSH Authentication Agent** in the list of services and press <kbd>Enter</kbd>. 4. In the "Startup type" menu, select **Disabled**. If the service status shows the agent is running, select **Stop**. 5. Select **Apply** > **OK**. The 1Password SSH agent can then take over and listen on the system-wide pipe at `\\.\pipe\openssh-ssh-agent`. _[Stop the Windows OpenSSH Authentication Agent service]_ #### Turn on the SSH agent in 1Password Follow these steps to turn on the SSH agent in 1Password: 1. Open the 1Password app, then select your account or collection at the top of the sidebar and select **Settings** > **Developer**. 2. Select **Set Up SSH Agent**, then choose whether or not you want to display SSH key names when you authorize connections. 3. (Optional) [Adjust the authorization options](#adjust-your-authorization-options) for when and how often the SSH agent will ask you to approve SSH requests. _[The SSH agent developer settings in the 1Password desktop app, with both checkboxes selected and a badge at the top that shows the agent is running.]_ If you previously turned off the SSH agent and would like to turn it back on, select the checkbox to **Use the SSH agent**. When you choose to display SSH key names when authorizing connections, it's easier for you to identify which key 1Password is requesting access to when authenticating a request from an SSH client. To display key names in authorization prompts, 1Password needs to [save the titles of your SSH Key items in local storage](/docs/ssh/agent/security#local-storage). To turn off this feature, deselect the checkbox to **Display key names when authorizing connections** in the Security section. To make sure the SSH agent keeps running, even when the 1Password app is closed: 1. Open 1Password, then select your account or collection at the top of the sidebar and select **Settings** > **General**. 2. Select the checkbox to **Keep 1Password in the notification area**. _[The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running.]_ **Linux:** 1. Open the 1Password app, then select your account or collection at the top of the sidebar and select **Settings** > **Developer**. 2. Select **Set Up SSH Agent**, then choose whether or not you want to display SSH key names when you authorize connections. 3. (Optional) [Adjust the authorization options](#adjust-your-authorization-options) for when and how often the SSH agent will ask you to approve SSH requests. _[The SSH agent developer settings in the 1Password desktop app, with both checkboxes selected and a badge at the top that shows the agent is running.]_ If you previously turned off the SSH agent and would like to turn it back on, select the checkbox to **Use the SSH agent**. When you choose to display SSH key names when authorizing connections, it's easier for you to identify which key 1Password is requesting access to when authenticating a request from an SSH client. To display key names in authorization prompts, 1Password needs to [save the titles of your SSH Key items in local storage](/docs/ssh/agent/security#local-storage). To turn off this feature, deselect the checkbox to **Display key names when authorizing connections** in the Security section. To make sure the SSH agent keeps running, even when the 1Password app is closed: 1. Open 1Password, then select your account or collection at the top of the sidebar and select **Settings** > **General**. 2. Select the checkbox to **Keep 1Password in the system tray**. _[The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running.]_ ## Step 4: Configure your SSH or Git client After you turn on the SSH agent in 1Password, you'll need to configure your SSH client to use the agent for authentication. **Mac:** Add the `IdentityAgent` snippet to your `~/.ssh/config` file: ``` Host * IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock" ``` If your `~/.ssh` folder or `config` file doesn't exist yet, create it first. You can also set the `SSH_AUTH_SOCK` environment variable in the shell where your SSH command runs: ```shell export SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ``` For an agent path that's easier to type, you can optionally run the following command to create a symlink for `~/.1password/agent.sock`: ```shell mkdir -p ~/.1password && ln -s ~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ~/.1password/agent.sock ``` Now your SSH clients will use the 1Password SSH agent for all hosts. If you prefer to migrate to the 1Password SSH agent gradually, you can configure your SSH clients to only use the SSH agent for one or more specific hosts, instead of all hosts. Learn more about [gradual migration](/docs/ssh/agent/advanced#gradual-migration). Some SSH clients don't support every configuration option that the `~/.ssh/config` file has to offer. Learn more about [SSH client compatibility](/docs/ssh/agent/compatibility/). By default, OpenSSH servers are configured to limit the amount of authentication attempts for an incoming SSH connection. Learn more about how to avoid the [SSH server six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). **Windows:** Additional configuration to use the SSH agent for authentication with your SSH clients isn't required. To use the SSH agent with Git, configure the [`core.sshCommand`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coresshCommand) variable in your Git config to use Microsoft OpenSSH: ``` git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe" ``` You can also manually edit your [`gitconfig` file](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup#:~:text=On%20Windows%20systems): ``` [core] sshCommand = C:/Windows/System32/OpenSSH/ssh.exe ``` For the best Git experience with 1Password, install the latest version of [Git for Windows](https://gitforwindows.org/) (version `2.33` or later). If you're using Windows Subsytem for Linux (WSL), you can [use the 1Password SSH agent with WSL](/docs/ssh/integrations/wsl). By default, OpenSSH servers are configured to limit the amount of authentication attempts for an incoming SSH connection. Learn more about how to avoid the [SSH server six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). **Linux:** Add the `IdentityAgent` snippet to your `~/.ssh/config` file: ``` Host * IdentityAgent ~/.1password/agent.sock ``` If your `~/.ssh` folder or `config` file doesn't exist yet, create it first. You can also set the `SSH_AUTH_SOCK` environment variable in the shell where your SSH command runs: ```shell export SSH_AUTH_SOCK=~/.1password/agent.sock ``` Now your SSH clients will use the 1Password SSH agent for all hosts. If you prefer to migrate to the 1Password SSH agent gradually, you can configure your SSH clients to only use the SSH agent for one or more specific hosts, instead of all hosts. Learn more about [advanced use cases](/docs/ssh/agent/advanced#gradual-migration). Some SSH clients don't support every configuration option that the `~/.ssh/config` file has to offer. Learn more about [SSH client compatibility](/docs/ssh/agent/compatibility/). By default, OpenSSH servers are configured to limit the amount of authentication attempts for an incoming SSH connection. Learn more about how to avoid the [SSH server six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). ## Step 5: Run a command Now you're ready to start using the 1Password SSH agent with GitHub. From your project directory, run: ``` git pull ``` If you don't have a project available on GitHub where you can run `git pull` now, you can run this command instead to quickly test your GitHub SSH setup: ``` ssh -T git@github.com ``` ## Step 6: Authorize the SSH request 1Password will ask you to allow your terminal or other SSH client to use your SSH key. You can approve this request using the authentication option indicated on the prompt (for example, Touch ID, Windows Hello, or your account password). If 1Password is locked, you'll also be prompted to unlock the app so the SSH agent can access your private keys. _[Authorization prompt showing a Touch ID icon.]_ _[Authorization prompt showing that the 1Password account password needs to be entered.]_ _[Authorization prompt showing a Windows Hello icon.]_ After approving the request, you can continue using the same SSH key for that application without being prompted again until 1Password locks or quits. You can also [configure your authorization settings](#adjust-your-authorization-options) to prompt more or less frequently. [Learn more about the 1Password SSH agent authorization model.](/docs/ssh/agent/security#authorization-model) ### Adjust your authorization options There are several options you can choose from to determine how long the agent remembers your SSH key approval and what usage you're approving for each key. These options determine when the SSH agent will ask you to approve SSH requests. #### In the 1Password settings Open 1Password, then select your account or collection at the top of the sidebar and select **Settings** > **Developer**. In the security settings for the SSH agent, you can choose the options that best suit your needs. You can change your settings at any time. 1Password can ask you to approve an SSH request: - **For each new application** (default): You'll be asked to authorize SSH requests from each new application to use a specific SSH key. - **For each new application and terminal session**: Similar to the first option, you'll be asked to authorize SSH requests from each new application to use a specific SSH key. If the application is a terminal emulator or an IDE with a built-in terminal, you'll also be asked to authorize requests for each new terminal tab in that application. You can choose how long 1Password will remember your key approval. - **Until 1Password locks** (default): Every time 1Password locks, your key approvals are wiped from the agent's memory and you'll be asked to reauthorize any previously approved SSH clients to use your keys. For example, if you approve the terminal application to use your SSH key for GitHub, then 1Password locks, you'll need to reapprove any new requests from the terminal to use your GitHub SSH key when 1Password unlocks. [Learn how to change your 1Password lock settings.](https://support.1password.com/auto-lock/) - **Until 1Password quits**: Every time 1Password quits, your key approvals are wiped from the agent's memory. Any agent sessions and background processes will also end. To use the SSH agent to authorize any new requests to use your SSH keys, you'll need to reopen 1Password. - **For a set amount of time**: You can choose from 4, 12, or 24 hours. If you select one of these options, your key approvals will remain in the agent's memory for that duration, even when 1Password is locked. You won't need to reauthorize new requests from the same applications to use the same SSH keys you've already approved, but you'll be prompted to unlock 1Password so the SSH agent can access your private key. #### In the authorization prompt Every authorization prompt for a client to use an SSH key includes the option to approve the use of that key for all applications. To turn on this option, select the checkbox to **Approve for all applications**. This option can be selected for individual SSH keys. It temporarily authorizes all applications running in the current OS user account on your device to use that SSH key for the duration of the agent session (depending on [the options you've selected in the developer settings](#in-the-1password-settings) in 1Password). You can use this option alongside your other settings. [Learn more about the authorization options for the SSH agent.](/docs/ssh/agent/security#authorization-options) ## Learn more - [Manage SSH keys](/docs/ssh/manage-keys#generate-an-ssh-key) - [Autofill public keys](/docs/ssh/public-key-autofill/) - [SSH client compatibility](/docs/ssh/agent/compatibility/) - [Advanced use cases](/docs/ssh/agent/advanced/) - [About 1Password SSH Agent security](/docs/ssh/agent/security/) - [Use the 1Password SSH agent with WSL](/docs/ssh/integrations/wsl) --- ## Sign Git commits with SSH Git version 2.34 and later supports signing commits and tags with SSH keys — no GPG key needed. This means you can use the [1Password SSH integration](/docs/ssh/) to create new Git signing keys in seconds, and use them with your terminal apps and other [Git clients](/docs/ssh/agent/compatibility/) without the private key ever leaving 1Password. You can also automatically configure Git commit signing with SSH in the 1Password app. When you sign your commits, they can be cryptographically verified using the SSH public keys associated with your [GitHub ](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification), [GitLab ](https://docs.gitlab.com/user/project/repository/signed_commits/ssh#configure-git-to-sign-commits-with-your-ssh-key), or [Bitbucket ](https://support.atlassian.com/bitbucket-cloud/docs/use-ssh-keys-to-sign-commits/) account. This ensures other people can verify that the changes were actually made by you. This is important because anyone with push rights to your repository can push new commits as any author, allowing them to impersonate others if commits aren't signed. [Learn how easy it is to use 1Password to sign your Git commits.](https://blog.1password.com/git-commit-signing/) ## Requirements Before you get started, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. Update to Git 2.34.0 or later. 4. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) 5. [Set up the 1Password SSH Agent.](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) ## Step 1: Configure Git commit signing with SSH To automatically configure Git commit signing with SSH globally: 1. Open the SSH key you want to use in your 1Password desktop app. 2. Select > **Configure Commit Signing**. 3. In the next window, select **Edit Automatically**. Or select Copy Snippet, then paste the snippet into your `~/.gitconfig` file manually. _[The Configure Git Commit Signing window showing options to edit your config file automatically or copy the configuration snippet manually.]_ You can also [configure SSH signing in a single repository](#configure-commit-signing-in-a-single-repository). 1Password will make the following changes to your Git config file: - Set `gpg.format` to `ssh`. - Set `user.signingkey` to the public key you chose to sign commits with. - Set `commit.gpgsign` to `true` so you don't need to include the `-S` flag with each commit. *(optional)* - Set `gpg.ssh.program` to the SSH signer binary provided by 1Password, so you don't have to set `SSH_AUTH_SOCK` yourself. *(optional)* :::tip If you use WSL on a Windows machine, learn how to set up the [1Password WSL integration](/docs/ssh/integrations/wsl) to authenticate SSH and Git commands and [sign your Git commits within WSL](/docs/ssh/integrations/wsl#sign-git-commits-with-ssh). ::: ## Step 2: Register your public key Now that you've configured SSH commit signing locally, you'll need to register your public key so that others can verify the authenticity of your commits. **GitHub:** To allow GitHub to verify your commits, visit the [GitHub SSH key settings ](https://github.com/settings/ssh/new) to register your SSH key for commit signing. You can use the 1Password browser extension to automatically fill in the public key and key title. Make sure you set the "Key type" to `Signing key` to allow your SSH key to be used for signing commits. _[The GitHub form to add a new SSH key, with signing key selected.]_ **GitLab:** To allow GitLab to verify your commits, visit the [GitLab SSH key settings ](https://gitlab.com/-/user_settings/ssh_keys) to register your SSH key for commit signing. You can use the 1Password browser extension to automatically fill in the public key and key title. Make sure you set the "Usage type" to either `Authentication & Signing` or `Signing` to allow your SSH key to be used for signing commits. _[The GitLab form to add a new SSH key, with authentication and signing selected.]_ **Bitbucket:** To allow Bitbucket to verify your commits, visit the [Bitbucket SSH key settings ](https://bitbucket.org/account/settings/ssh-keys/) to register your SSH key for commit signing. You can use the 1Password browser extension to automatically fill in the public key and key title. _[The Bitbucket form to add a new SSH key.]_ **Locally:** To verify SSH signatures locally, you'll need to create an [allowed signers file ](https://www.man7.org/linux/man-pages/man1/ssh-keygen.1.html#ALLOWED_SIGNERS) and configure Git to use it. You can choose to configure this globally, for example: ```shell touch ~/.ssh/allowed_signers git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers ``` Or to tie it to a single repository, for example: ```shell touch .git/allowed_signers git config --local gpg.ssh.allowedSignersFile .git/allowed_signers ``` In the allowed signers file, add pairs of emails and public keys you'd like to trust: ```text title="allowed_signers" wendy@appleseed.com ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO ``` You can share this file with others and could even consider checking it into Git, similar to a `CODEOWNERS` file. ## Step 3: Commit and push your code Now that you're all set up, you can commit some code: ``` git commit -m "Signing my first commit with SSH" ``` You'll be prompted to authorize your SSH key the same way you unlock the 1Password app (for example, with Touch ID or Windows Hello). If you've chosen to use the same key to sign as you do to push and pull, you can now also push without requiring additional authorization: ``` git push ``` ## Step 4: Verify your commit signature **GitHub:** If you look at your commit history on GitHub, you should see the `Verified` badge show up on your SSH-signed commits. If you select it, you can see the SSH key used to sign it. _[A GitHub commit marked with the verified badge and showing the SSH public key used to sign.]_ **GitLab:** If you look at your commit history on GitLab, you should see the `Verified` badge show up on your SSH-signed commits. If you select it, you can see the SSH key used to sign it. _[A GitLab commit marked with the verified badge and showing the SSH public key used to sign.]_ **Bitbucket:** If you look at your commit history on Bitbucket, you should see a verified checkmark show up on your SSH-signed commits. If you select it, you can see the SSH key used to sign it. _[A Bitbucket commit marked with the verified badge and showing the SSH public key used to sign.]_ **Locally:** To verify commits locally, run the following command: ```shell git log --show-signature ``` ## Advanced configuration ### Configure commit signing in a single repository You can enable Git commit signing with SSH for specific repositories or directories instead of globally. To do this: 1. Open the SSH key you want to use in your 1Password desktop app. 2. Select > **Configure Commit Signing**. 3. In the next window, select **Copy Snippet**. 4. Paste the snippet in the repository's `<git-repo>/.git/config` file instead of the global `~/.gitconfig` file. ### Configure multiple commit signing setups If you want to configure multiple commit signing setups, you can use the `includeIf` directive in your `~/.gitconfig`. For example, to use an SSH commit signing setup with 1Password as your default configuration and a non-1Password GPG setup for the `/work/acme` subdirectory: ```toml title="~/.gitconfig" [user] name = Wendy Appleseed email = wendy@appleseed.com signingkey = ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO [commit] gpgsign = true [gpg] format = ssh [gpg "ssh"] program = /Applications/1Password.app/Contents/MacOS/op-ssh-sign [includeIf "gitdir:~/work/acme/"] path = ~/work/acme/.gitconfig ``` ```toml title="~/work/acme/.gitconfig" [user] email = wendy.appleseed@acme.com signingkey = 6A40D13BBB936F443084E8C9292E4F983136B860 [gpg] format = openpgp ``` In this example, every repository under `~/work/acme` will use the GPG configuration, while the SSH configuration will be used everywhere else. ### Configure commit signing in remote environments You can [set up SSH agent forwarding](/docs/ssh/agent/forwarding) to authenticate Git requests and sign commits in remote environments, like from a [cloud development environment](/docs/ssh/agent/forwarding#cde) or [remote workstation](/docs/ssh/agent/forwarding#remote-workstation). ## Get help If Git says that SSH is an unsupported format If you see the following error message, then your Git version may be outdated: ```text error: unsupported value for gpg.format: ssh ``` Support for SSH commit signing was added to Git in version **2.34**. Run this command to check your Git version: ```shell git --version ``` It's common for operating systems and Git GUI clients to ship with an outdated version of Git out of the box. To install a more up-to-date version, see the [Git install docs. ](https://git-scm.com/downloads) In the case of Git GUI clients, check the app preferences to see if they allow you to change the Git binary to a more up-to-date version. If your commits fail after you change your Git configuration If you see one of the following error messages, it's likely related to your `user.signingkey` value. Make sure that's set to a valid SSH public key. ```text fatal: failed to write commit object ``` ```text could not deserialize public key ``` ```text No such file or directory ``` If your `user.signingkey` is set correctly in your `~/.gitconfig` file, check the value at the repository level by running the following command from your repo's directory: ```shell git config user.signingkey ``` Example of a correct output: ```text ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO ``` If the signing key is not the SSH public key you've configured in your `~/.gitconfig`, you may have a [local override](#local-git-overrides) in your repository. If you see errors related to the allowed signers file If you see the following error message, make sure you've properly configured your [allowed signers file](#step-2-register-your-public-key): ```text error: gpg.ssh.allowedSignersFile needs to be configured and exist for ssh signature verification ``` This error should not block you from browsing your commit log - it just prevents you from locally verifying the commit authenticity. If your SSH-signed commit doesn't get verified by Git, GitHub, GitLab, and/or Bitbucket If you believe you've signed your commits through SSH but they're not showing up as verified, there are a few things that could be happening: #### Commit author email mismatch Commit signatures will only show up as verified if the registered public key matches the commit author email. Make sure it matches the email you've registered on [GitHub ](https://github.com/settings/emails), [GitLab ](https://gitlab.com/-/user_settings/profile), or [Bitbucket ](https://id.atlassian.com/manage-profile/profile-and-visibility) in your allowed signers file. :::info Case-sensitive email addresses If your signed commits are verified locally but aren't verified on GitLab.com or Bitbucket, check for any case mismatches in your email address. For example, if the email address in your GitLab or Bitbucket account is `wendy@appleseed.com` but your `~/.gitconfig` file uses `Wendy@appleseed.com`, your commits will show as unverified in those accounts. ::: If you have the correct email in your `~/.gitconfig`, check that the settings have correctly propagated down to the repository level as well. To validate this, run the following command from your repo's directory: ```shell git config user.email ``` If this is not the email you've configured in your `~/.gitconfig`, you may have a [local override](#local-git-overrides) in your repository. #### Misconfigured public key On GitHub, visit the [SSH key settings ](https://github.com/settings/keys) and check that the key you've locally configured as `user.signingkey` shows up under "Signing keys". On GitLab, visit the [SSH key settings ](https://gitlab.com/-/user_settings/ssh_keys) and check that the key you've locally configured as `user.signingkey` shows up under "Your SSH keys". On Bitbucket, visit the [SSH key settings ](https://bitbucket.org/account/settings/ssh-keys/) and check that the key you've locally configured as `user.signingkey` shows up under "SSH keys". For a local allowed signers file, make sure your public key is present and matches your email. #### Unsupported Git client Most Git clients support SSH commit signing out of the box, but there are [a few exceptions](/docs/ssh/agent/compatibility/). Even though you may have configured Git correctly, a Git client that doesn't support SSH commit signing will leave your commit unsigned. Make sure to also [check that you're on the latest version of your Git client](#get-help). #### Local Git overrides Even though you may have configured your `~/.gitconfig` well, make sure to also check that the settings have correctly propagated down to the repository level. To validate this, run the following command from your repo's directory: ```shell cat << EOF gpg.format: $(git config gpg.format) user.signingkey: $(git config user.signingkey) gpg.ssh.program: $(git config gpg.ssh.program) commit.gpgsign: $(git config commit.gpgsign) EOF ``` Example of a correct output: ```text gpg.format: ssh user.signingkey: ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO gpg.ssh.program: /Applications/1Password.app/Contents/MacOS/op-ssh-sign commit.gpgsign: true ``` If this output does not match up with what you've configured in your `~/.gitconfig`, unset the local values: ```shell git config --local --unset gpg.format git config --local --unset user.signingkey git config --local --unset gpg.ssh.program git config --local --unset commit.gpgsign ``` If you still end up with the wrong value somewhere, you can check where it originates from using the `--show-origin` flag: ```shell cat << EOF gpg.format: $(git config --show-origin gpg.format) user.signingkey: $(git config --show-origin user.signingkey) gpg.ssh.program: $(git config --show-origin gpg.ssh.program) commit.gpgsign: $(git config --show-origin commit.gpgsign) EOF ``` --- ## Use the 1Password SSH agent with WSL The 1Password Windows Subsystem for Linux (WSL) integration allows you to authenticate SSH and Git commands and sign your Git commits within WSL using the 1Password SSH agent running on your Windows host. The 1Password integration supports both WSL 1 and WSL 2. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Windows](https://1password.com/downloads/windows). 3. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) 4. [Set up the 1Password SSH agent](/docs/ssh/get-started/) on your Windows host and make sure it's running. 5. [Install Windows Subsystem for Linux on Windows ](https://learn.microsoft.com/windows/wsl/install) with your preferred Linux distribution. To use [SSH Git commit signing with the 1Password WSL integration](#sign-git-commits-with-ssh), you'll also need: - Git 2.34.0 or later. - A 64-bit version of Windows 10 or later. Arm-powered Windows devices aren't supported. ## How the integration works With WSL, you can [run Windows tools from the command line ](https://learn.microsoft.com/windows/wsl/filesystems#run-windows-tools-from-linux), such as the Windows OpenSSH client (`ssh.exe`). The 1Password WSL integration leverages the [interoperability ](https://learn.microsoft.com/windows/wsl/filesystems#interoperability-between-windows-and-linux-commands) built into WSL to forward SSH requests to the 1Password SSH agent on Windows. Instead of forwarding SSH *agent* requests, like with standard OpenSSH agent forwarding, you can effectively forward the entire SSH request from WSL to the `ssh.exe` process running on Windows. The `ssh.exe` process then uses the 1Password SSH agent on your Windows host to authenticate the request. This also means that any [changes to your SSH configuration](/docs/ssh/agent/advanced) need to be made in your Windows `%USERPROFILE%/.ssh/config` file, rather than the file on your WSL instance. ## Forward an SSH request 1. Check if the 1Password SSH agent is running **on your Windows host** with the following command: ```powershell ssh-add.exe -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI Git Authentication Key (ED25519) ``` If the agent is running, a list with one or more SSH keys will be returned. These are the SSH keys you stored in 1Password that are available to use with the agent for SSH requests. 2. Check if WSL is forwarding SSH requests successfully by running the following command **in your WSL instance**: ```shell ssh-add.exe -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI Git Authentication Key (ED25519) ``` You should see the same list of SSH keys returned as you did when you ran the command on your Windows host. If you do, then WSL is forwarding your SSH requests to your Windows host.[Get help](#error-command-not-found) if you don't see your SSH key(s) listed when you run the `ssh-add.exe -l` command. 3. If you see your SSH key(s) listed in WSL, try to run an SSH request, replacing `ssh` with `ssh.exe` in your command. For example: ```shell ssh.exe -T git@github.com ``` You should see a prompt from 1Password to authorize the SSH request: _[SSH authorization prompt for WSL.]_ You can now use the 1Password SSH agent to forward SSH requests between your Windows host and WSL instance. ## Configure Git to use `ssh.exe` To use the 1Password SSH agent to authenticate Git commands in WSL, you can configure Git to use `ssh.exe` as the `core.sshCommand`. To set this variable globally, run the following command in WSL: ```shell git config --global core.sshCommand ssh.exe ``` ## Sign Git commits with SSH :::info 1Password for Windows 8.11.18 and later uses a new [MSIX installer](https://support.1password.com/cs/1password-msix-installer/), which automatically [updates the app data path](#error-cannot-run). If you set up the SSH agent to authenticate Git commands in WSL prior to version 8.11.18, you'll need to follow the steps below to configure Git commit signing again. ::: With Git configured to use `ssh.exe`, you can also use the integration to sign Git commits from WSL. To configure Git commit signing with SSH globally in WSL: 1. On your Windows host, open the 1Password app, then open the SSH key you want to use. 2. Select > **Configure Commit Signing**. 3. In the next window, select the checkbox to **Configure for Windows Subsystem for Linux (WSL)**, then select **Copy Snippet**. 4. In your WSL instance, paste the snippet into your `~/.gitconfig` file. _[The Configure Git Commit Signing window showing the checkbox to configure for WSL and the configuration snippet.]_ You can also [configure SSH signing in a single repository](/docs/ssh/git-commit-signing#configure-commit-signing-in-a-single-repository). 1Password will make the following changes to your Git config file: - Set `gpg.format` to `ssh`. - Set `user.signingkey` to the public key you chose to sign commits with. - Set `commit.gpgsign` to `true` so you don't need to include the `-S` flag with each commit. *(optional)* - Set `gpg.ssh.program` to the SSH signer binary provided by 1Password. After you set up Git commit signing on WSL, you can use the same steps as your Windows host to test the configuration. [Register your public key](/docs/ssh/git-commit-signing#step-2-register-your-public-key), then [commit some code](/docs/ssh/git-commit-signing#step-3-commit-and-push-your-code) and [verify your commit is signed](/docs/ssh/git-commit-signing#step-4-verify-your-commit-signature). ## Optional: Add an alias for SSH commands If you plan to use the 1Password SSH agent on your Windows host to authenticate SSH requests other than Git, you can optionally [create aliases in your Bash profile ](https://linux.die.net/Bash-Beginners-Guide/sect_03_05.html) to use `ssh` and `ssh-add` on the command line in place of `ssh.exe` and `ssh-add.exe`. This isn't required, but it can be convenient to use the same SSH commands across all your platforms. In your `~/.bashrc` or `~/.bash_aliases` file, add the following aliases: ```shell alias ssh='ssh.exe' alias ssh-add='ssh-add.exe' ``` ## Authorization model The 1Password SSH agent uses the same [authorization model](/docs/ssh/agent/security#authorization-model) with the WSL integration as it does on other platforms. When you approve an SSH key request for a WSL session, only the current session is authorized to use that key. If you open a new WSL session or tab, you'll be prompted to approve the SSH request again. [Learn more about the 1Password SSH agent authorization model.](/docs/ssh/agent/security#authorization-model) ## Troubleshooting ### Error: `command not found` If you see a `command not found` error when you run the `ssh-add.exe -l` command in WSL, OpenSSH may not be in your `PATH`. Try to run the command again using the full executable path: ```shell /mnt/c/Windows/System32/OpenSSH/ssh-add.exe -l ``` If you still see an error, check if the [interoperability setting ](https://learn.microsoft.com/windows/wsl/wsl-config#interop-settings) (`[interop]`)is turned on in your WSL config file. If it is, the entry will look like this: ```text [interop] enabled = true ``` If you see `enabled = false` instead, set the `enabled` value to `true`. ### Error: `cannot run` 1Password for Windows 8.11.18 and later uses an [MSIX installer](https://support.1password.com/cs/1password-msix-installer/), which updates the app data path previously used by the EXE installer. If you configured the SSH agent to authenticate Git commands in WSL using an earlier version of the app, you may see the following error message: ``` fatal: cannot run /mnt/c/Users/<username>/AppData/Local/1Password/app/8/op-ssh-sign-wsl: No such file or directory ``` To fix the issue, you'll need to [reconfigure Git commit signing for WSL](#sign-git-commits-with-ssh). This will add the updated path to your `.gitconfig` file. ```text title="Deprecated path (8.11.16 and earlier)" /mnt/c/Users/<Username>/AppData/Local/1Password/app/8/op-ssh-sign-wsl ``` ```text title="New path (8.11.18 and later)" /mnt/c/Users/<Username>/AppData/Local/Microsoft/WindowsApps/op-ssh-sign-wsl.exe ``` --- ## Manage SSH keys(Ssh) You can use 1Password to manage all your SSH keys. [Generate SSH Key items](#generate-an-ssh-key) – with public keys, fingerprints, and private keys – right in 1Password. And if you have existing SSH keys, you can [import them into 1Password](#import-an-ssh-key). You can also [export your SSH keys](#export-an-ssh-key) from 1Password at any time. :::tip If you manage multiple SSH keys and you want to use them with the [1Password SSH Agent](/docs/ssh/agent/), learn more about how to avoid the [SSH server six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). ::: ## Requirements Before you can use 1Password to manage your SSH keys, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. (Optional) [Install 1Password CLI](/docs/cli/get-started#step-1-install-1password-cli) `2.20.0` or later. Required to create SSH keys using 1Password CLI. ## Generate an SSH key Generate an SSH key in the 1Password desktop apps or with 1Password CLI to use anywhere you need one. **Desktop apps:** 1. Open and unlock the 1Password app, then navigate to your [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault in the sidebar. If you've configured the SSH agent for any shared or custom vaults, you can generate your SSH key in one of those vaults instead. 2. Select **New Item**, then select **SSH Key**. 3. Select **Add Private Key** > **Generate a New Key**. 4. Choose a [key type](#supported-ssh-key-types), then select **Generate**. 5. You can edit the name of your key and make any other changes. When you're done, select **Save**. _[The 1Password save dialog for an SSH Key item with the option to generate an Ed25519 key type selected.]_ **1Password CLI:** 1. Open the terminal and [sign in](/docs/cli/get-started#step-3-enter-any-command-to-sign-in) to your 1Password account. 2. To generate an SSH key, run: ```shell op item create --category ssh --title "My SSH Key" ``` 1Password CLI will generate an [Ed25519](#ed25519) key by default. Learn how to [create an RSA key](/docs/cli/ssh-keys#generate-an-ssh-key) instead. 3. After you run the command, 1Password CLI will generate an SSH key and save it as a new item in your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault, then will print the key to stdout with the private key redacted. SSH keys are saved in your Personal, Private, or Employee vault by default. See the full [1Password CLI documentation](/docs/cli/ssh-keys/) for more information about how to manage your SSH keys on the command line. ## Import an SSH key {#import-an-ssh-key} If you have an SSH key you want to save in 1Password, you can import it. 1. Open and unlock the 1Password desktop app, then navigate to your [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault in the sidebar. If you've configured the SSH agent for any shared or custom vaults, you can generate your SSH key in one of those vaults instead. 2. Select **New Item** > **SSH Key**. 3. Select **Add Private Key** > **Import a Key File**, then navigate to the location of the SSH key you want and select **Import**. You can also drag and drop your SSH key file directly into the new SSH item or paste it from your clipboard. 4. If your SSH key is encrypted with a passphrase, enter the passphrase and select **Decrypt**. You'll only need to enter the passphrase once. After you import the SSH key into 1Password, it'll be encrypted according to the [1Password security model](https://support.1password.com/1password-security#encryption). 5. When you're done, select **Save**. _[A new SSH Key item with Import a Key File selected.]_ :::tip Is your passphrase saved in 1Password? If the passphrase for your SSH key is already saved in 1Password, use Quick Access to find and copy it without needing to switch context. ::: ### Key import errors If you see one of the error messages below when you import an SSH key in 1Password, check if there's an issue with the type of key, the file format, or the encryption: <details className="slim-details"> **If you see a message that your SSH key isn't supported** If you see a message that your SSH key isn't supported, make sure you're importing a [supported Ed25519 or RSA (2048, 3072, or 4096-bit) key](/docs/ssh/manage-keys#supported-ssh-key-types). Other key lengths and other key types, such as **DSA** or **ECDSA** keys, aren't supported. To check the key type and bit length, run the following command: ```shell ssh-keygen -l -f <path/to/your/key> ``` RSA keys also require a minimum public exponent of **65,537** to meet [NIST standards](https://csrc.nist.rip/library/NIST%20SP%20800-078-2%20Cryptographic%20Algorithms%20and%20Key%20Sizes%20for%20Personal%20Identification%20Verification%20(PIV),%202010-02.pdf). RSA keys with a public exponent less than 65,537 aren't supported. To check the size of the public exponent for your key, run the following command: ```shell openssl rsa -text -in <path/to/your/key> | grep publicExponent ``` <details className="slim-details"> **If you see a message that your SSH key file couldn't be read** If you see a message that your SSH key file couldn't be read, make sure the key file is in a supported format. 1Password supports **PKCS#1**, **PKCS#8**, and **OpenSSH** formats. Keys that use a different file format, such as PuTTYgen `.ppk`, aren't supported. <details className="slim-details"> **If you see a message that your SSH key couldn't be decrypted** If you see a message that your SSH key couldn't be decrypted, it could be that it's encrypted with an unsupported and outdated cipher such as **RC4**. You can re-encrypt your key file so that it uses a more modern algorithm and then try importing it again. To do this, run the following command: ```shell ssh-keygen -p -f path/to/your/key ``` If you still can't import your SSH key, you can use 1Password to [generate a new SSH key](/docs/ssh/manage-keys#generate-an-ssh-key) using the latest standards. ## Export an SSH key You can export a private SSH key from 1Password at any time. 1. Open and unlock the 1Password desktop app. 2. Choose the SSH key you want to export, then select the private key field. 3. Choose the export format you need: **OpenSSH** or **PKCS#8**. If you imported a PKCS#1-formatted key into 1Password, you will also have the option to export that key in **PKCS#1** format. 4. Choose how you want to export your private key: - To encrypt your exported private key (OpenSSH format only), enter a passphrase, then select **Copy Encrypted Key** or **Download Encrypted Key**. - To export your private key in plaintext, leave the passphrase field empty (if there is one), then select **Copy Unencrypted Key** or **Download Unencrypted Key**. _[A GitHub SSH key item with the private key field highlighted to show the Export option.]_ _[The export dialog for a private key with an empty passphrase field and copy and download buttons.]_ :::warning[Keep your private keys safe] 1Password can't protect SSH keys that you store outside of your account. If you need to export a private key, we recommend you save it in a secure location. Don't store unencrypted private keys on disk. ::: ## Share a public key {#share-a-public-key} 1Password will automatically generate the public key and fingerprint for each private key you create so you can share it with the services and people who need it. You can copy or download the public key of an SSH key in the right format every time, and you can use the fingerprint to compare and identify your keys across all your services. For platforms that let you provide public keys in the browser (often found in an SSH Key settings panel), you can use 1Password in your browser to [fill your public key](/docs/ssh/public-key-autofill/). You can also copy your public key from the item view in 1Password and share it where needed, or use [Quick Access](https://support.1password.com/quick-access/) to find your public key even faster without needing to switch context. _[Copy or download your public key to share it with others.]_ ## Supported SSH key types 1Password supports the following key types, formats, and encryption algorithms: - **Key types**: [Ed25519](#ed25519) and [RSA](#rsa) (2048, 3072, and 4096-bit) - **Formats**: PKCS#1, PKCS#8, and OpenSSH - **Encryption**: AES and 3DES (all supported key formats), and ChaCha20-Poly1305 (OpenSSH format only) ### Ed25519 Ed25519 is the fastest and most secure key type available today and is the option recommended by most Git and cloud platforms. Ed25519 is the default suggestion when you generate a new SSH key in 1Password and the key is automatically set to 256 bits. The Ed25519 key type was first introduced in 2014 with [OpenSSH 6.5](https://www.openssh.com/releasenotes.html). If you need to connect to an older server that isn't using OpenSSH 6.5 or later, an Ed25519 key won't work. ### RSA RSA is one of the oldest key types available and is compatible with most servers, including older ones. Compared to Ed25519, RSA is considerably slower, particularly with decryption, and is only considered secure if it's 2048 bits or longer. 1Password supports 2048-bit, 3072-bit, and 4096-bit RSA keys. ## View SSH keys in 1Password 7 Generating, importing, and sharing SSH keys requires 1Password 8. Any SSH keys that you generate or import can be viewed and copied in the 1Password 7 apps on your other devices. Make sure you're using an [updated version](https://support.1password.com/update-1password/) of 1Password 7 to view or copy your public or private keys. --- ## 1Password for SSH & Git Introducing 1Password for SSH & Git, the single source of truth for all your SSH keys. With 1Password, you can: - [Generate and import](/docs/ssh/manage-keys/) your SSH keys. - [Autofill public keys](/docs/ssh/public-key-autofill/) in your browser for Git and other cloud platforms. - Automatically configure [Git commit signing with SSH](/docs/ssh/git-commit-signing/) from the 1Password app. - Use the [1Password SSH Agent](/docs/ssh/agent/) to authenticate all your Git and SSH workflows. _[A terminal with a git push command, overlaid with a 1Password authorization prompt to approve the request to use an SSH key.]_ The SSH agent works with your existing SSH clients and acts as their key provider. Use your keys in your SSH workflows, like when you work with Git to check code into source control, or when you log in to virtual machines. 1Password stores all your SSH keys behind secure end-to-end encryption, allowing you to access your keys when you need them without your SSH keys ever leaving 1Password. ## Quick start ### [Get started](/docs/ssh/get-started/) If you're setting up SSH in 1Password for the first time, start here. ## Guides ### [Manage SSH keys](/docs/ssh/manage-keys/) Learn how to generate and import SSH keys, and how to copy or download your public key if you need to share it. ### [Autofill public keys](/docs/ssh/public-key-autofill/) Learn how to use 1Password in your browser to fill your public keys on your favourite Git or cloud platforms. ### [Sign Git commits with SSH](/docs/ssh/git-commit-signing/) Learn how to automatically configure Git commit signing with SSH through the 1Password app. ### [Advanced use cases](/docs/ssh/agent/advanced/) Learn how to configure the 1Password SSH agent for specific hosts and how to avoid rate limits with OpenSSH servers. ### [1Password agent config file](/docs/ssh/agent/config/) Learn how to create and customize an SSH agent config file if you need to use SSH keys from shared or custom vaults or have more fine-grained control over the behavior of the SSH agent. ## Reference documentation ### [SSH client compatibility](/docs/ssh/agent/compatibility/) Learn which SSH and Git clients have been tested with the 1Password SSH agent. ### [About 1Password SSH Agent security](/docs/ssh/agent/security/) Learn about the authorization model for the 1Password SSH agent, how it's different from the OpenSSH agent, and what's kept in local storage. --- ## Autofill public keys To use the SSH keys you saved in 1Password to connect to your favorite Git or cloud platforms, you'll need to provide your public key to those services. [Use 1Password in your browser](https://support.1password.com/getting-started-browser/) to fill your public key on those sites, anywhere you see the 1Password icon. Or copy your public key from the SSH key item in 1Password and paste it into the public key area of the website. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. [Install the 1Password browser extension.](https://1password.com/downloads/browser-extension) 4. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) ## AWS CodeCommit Visit the **Security credentials** tab of your [IAM user](https://console.aws.amazon.com/iam/home#/users) to add a new key: ## Azure DevOps Visit the **SSH public keys** page of your user settings to add a new key: ## Bitbucket Visit the [Bitbucket SSH key settings](https://bitbucket.org/account/settings/ssh-keys/) to add a new key: It also works for [access keys](https://support.atlassian.com/bitbucket-cloud/docs/add-access-keys/). ## DigitalOcean Visit your [account security settings](https://cloud.digitalocean.com/account/security) to add a new key: ## GitHub Visit the [GitHub SSH key settings](https://github.com/settings/ssh/new) to add a new key: You can also autofill [deploy keys](https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys). ## GitLab Visit the [GitLab SSH key settings](https://gitlab.com/-/user_settings/ssh_keys) to add a new key: It also works for [deploy keys](https://docs.gitlab.com/user/project/deploy_keys/). ## Gitpod Visit the [Gitpod SSH key settings](https://gitpod.io/keys) to add a new key: ## Google Compute Engine Visit the [Google Compute Engine metadata settings](https://console.cloud.google.com/compute/metadata?tab=sshkeys) to add a new key: ## IBM Cloud (VPC) Visit the [**SSH keys** section](https://cloud.ibm.com/vpc-ext/compute/sshKeys) in the VPC Infrastructure console to add a new key: ## IBM Cloud (Classic) Visit the [**SSH keys** section](https://cloud.ibm.com/gen1/infrastructure/ssh-keys) in the Classic Infrastructure console to add a new key: ## JetBrains Space Visit the **Git Keys** tab in your Space profile settings to add a new key: ## Linode Visit the [**SSH Keys** section in your profile](https://cloud.linode.com/profile/keys) to add a new key: ## Microsoft Azure Visit the [**SSH keys** section in the Azure portal](https://portal.azure.com#create/Microsoft.SshKey) to add a new key: ## Ngrok Visit the [**SSH Public Keys** section in the Ngrok dashboard](https://dashboard.ngrok.com/tunnels/ssh-keys/new) to add a new key: ## Vultr Visit the [Vultr SSH key settings](https://my.vultr.com/settings#settingssshkeys) to add a new key: --- ## Get started with 1Password Service Accounts With 1Password Service Accounts, you can build tools to automate secrets management in your applications and infrastructure without deploying additional services. Service accounts can: - Create, fetch, edit, delete, and share items. - Read environment variables from [1Password Environments](/docs/environments). - Create vaults. - Delete vaults. A service account can only delete a vault it created. See service account security. - Retrieve information about users and groups. Each service account has a [service account token](/docs/service-accounts/security#service-accounts-and-token-generation) that you can provide as an environment variable for authentication. You can choose which vaults and [Environments](/docs/environments) the service account can access and its permissions in each vault. **Limitations** Service accounts have the following limitations: - Service accounts have [rate limits and request quotes](/docs/service-accounts/rate-limits/). - You can't grant a service account access to your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault, or your default [Shared](https://support.1password.com/1password-glossary#shared-vault) vault. - Service accounts can only be granted read access to Environments. - Service accounts only work with 1Password CLI version 2.18.0 or later. See [Use service accounts with 1Password CLI](/docs/service-accounts/use-with-1password-cli/). - You can't use service accounts with the [Kubernetes Operator](/docs/k8s/operator/) (only the [Kubernetes Secrets Injector](/docs/k8s/injector/)). ## Requirements Before you can create and use service accounts, you'll need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - Have adequate account permissions to create service accounts. If you don't see the option to create service accounts, ask your administrator to [give you access to create and manage service accounts](/docs/service-accounts/manage-service-accounts#manage-who-can-create-service-accounts). ## Create a service account You can create a service account on 1Password.com or with [1Password CLI](/docs/cli/). Service account permissions, vault access, and Environment access are immutable. If you want to grant a service account access to additional vaults or Environments, change the permissions it has in the vaults it can access, or change its ability to create new vaults, you'll need to create a new service account with the appropriate permissions and access. **1Password.com:** To create a service account on 1Password.com: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Open the [service account creation wizard](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/?source=dev-portal).Or navigate to **Developer** > **Directory**, select **Other** under Infrastructure Secrets Management, then select **Create a Service Account**. 3. Follow the onscreen instructions: 1. Choose a name for the service account. 2. Choose whether the service account can create vaults. 3. Choose the vaults the service account can access.You can't grant a service account access to your built-in Personal, Private, or Employee vault, or your default Shared vault. 4. Select the settings icon next to each vault to choose the permissions the service account has in the vault. This can't be changed later. 5. Choose which [1Password Environments](/docs/environments) the service account can access. This can't be changed later. 5. Select **Create Account** to create the service account. 6. Select **Save in 1Password** to save the service account token in your 1Password account. In the next window, enter a name for the item and choose the vault where you want to save it. :::danger The service account creation wizard only shows the service account token once. **Save the token in 1Password** immediately to avoid losing it. Treat this token like a password, and don't store it in plaintext. ::: You can find your new service account under "Service accounts" on the [**Developer**](https://start.1password.com/developer-tools/active) page. **1Password CLI:** :::note Use the [service account creation wizard](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/?source=dev-portal) on 1Password.com if you want to create a service account that can access 1Password Environments. ::: To create a service account with 1Password CLI: 1. Make sure you have the latest version of [1Password CLI](/docs/cli/get-started/) on your machine. 2. Create a new service account using the [`op service-account create` command](/docs/cli/reference/management-commands/service-account#service-account-create): ```shell op service-account create <serviceAccountName> --expires-in <duration> --vault <vault-name:<permission>,<permission> ``` Available permissions: `read_items`, `write_items` (requires `read_items`), `share_items` (requires `read_items`) Include the `--can-create-vaults` flag to allow the service account to create new vaults. If the service account or vault name contains one or more spaces, enclose the name in quotation marks (for example, “My Service Account”). You don't need to enclose strings in quotation marks if they don't contain spaces (for example, myServerName). Service accounts can't be modified after they're created. If you need to make changes, revoke the service account and create a new one. 3. Save the service account token in your 1Password account. 4. If you want to start using the service account with 1Password CLI, [export the token to the `OP_SERVICE_ACCOUNT_TOKEN` environment variable](/docs/service-accounts/use-with-1password-cli#get-started). For example, to create a service account named `My Service Account` that has read and write permissions in a vault named `Production`, can create new vaults, and expires in 24 hours: ```shell op service-account create "My Service Account" --can-create-vaults --expires-in 24h --vault Production:read_items,write_items ``` :::danger 1Password CLI only returns the service account token once. **Save the token in 1Password** immediately to avoid losing it. Treat this token like a password, and don't store it in plaintext. ::: :::caution If your [sign-in address](https://support.1password.com/1password-glossary#sign-in-address) changes, you'll need to [rotate your service account tokens](/docs/service-accounts/manage-service-accounts#rotate-token). ::: ## Next steps Explore the following to learn about how you can use service accounts. - [Use a service account with 1Password CLI.](/docs/service-accounts/use-with-1password-cli/) - [Manage a service account.](/docs/service-accounts/manage-service-accounts/) - [Integrate a service account with a CI/CD pipeline.](/docs/ci-cd/) - [Integrate a service account with Kubernetes.](/docs/k8s/integrations/) :::tip Need help? [Join our Developer Slack workspace](https://developer.1password.com/joinslack) to ask questions and provide feedback. ::: --- ## Manage service accounts ## Manage active service accounts Owners and administrators can manage all service accounts created by their team. Other team members with the [permission to create service accounts](#manage-who-can-create-service-accounts) can manage their own service accounts, but not service accounts created by other people. You can view and manage a service account from its overview page on 1Password.com. The service account overview page shows information about the service account, such as the vaults and [1Password Environments](/docs/environments) it can access, vault permissions, and recent activity. To manage a service account, go to the service account overview: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose the service account you want to manage. ### Create a usage report for a service account To create a [usage report](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault) for a service account: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose a service account. 4. On the service account overview page, select **View Item Usage Report**. Usage reports for service accounts include information on the number of vaults and items a service account can access, an overview of vaults where a service account has accessed items, when those items were last accessed, and the action performed. ### Change a service account's name {#change-name} To change a service account's name: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose a service account. 4. Select **Edit Details**. 5. Type a new name, then select **Save**. ### Rotate a service account token {#rotate-token} Rotating a service account token generates a new token with the same permissions. You can also specify an expiration for the current token, so you have time to update to the new token without any interruption in service. Take note of any places where you may need to update a service account token before you rotate it. This helps you set a more reasonable expiration time. To rotate a service account token: 1. [Sign in](https://start.1password.com/sign-in/) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose a service account. 4. Under the Token section, select **Rotate Token**. 5. Select a value for **Expire existing token** to set when the token will expire. For example, you can set the existing token to expire **now** (immediately), in **1 hour**, or in **3 days**. 6. Enter the service account name to confirm. 7. Select **Rotate Token**. 8. Select **Save in 1Password** to save the new token value in 1Password. :::caution If your [sign-in address](https://support.1password.com/1password-glossary#sign-in-address) changes, make sure to rotate your service account tokens. Your tokens will redirect to the new sign-in address for 30 days. ::: ### Revoke a service account token {#revoke-token} Revoking a service account token immediately removes its access to 1Password vaults. You might want to revoke a token if it becomes compromised or unnecessary. To revoke a service account token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose a service account. 4. Under the Token section, select **Revoke Token**. 5. Enter the service account name to confirm, then select **Revoke Token**. ## Manage service account settings With 1Password Teams and 1Password Business, you can manage who on your team can create service accounts and which vaults the service accounts can access. ### Manage who can create service accounts By default, only [owners and administrators](https://support.1password.com/groups/) can create and manage service accounts in 1Password Teams and 1Password Business. To allow other groups to create service accounts, an owner or administrator can: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Permissions** at the top of the Developer page, then select **Service Account**. 4. Select **Manage groups**, choose the groups you want to allow to create service accounts, then select **Update Groups**. Team members in the selected groups will be able to create service accounts. To manage which individual team members can create service accounts, change from the Groups tab to the People tab. Select **Manage People**, choose the team members you want to allow to create service accounts, then select **Update People**. Each team member with permission to create service accounts will only be able to manage their own service accounts, not service accounts created by other people. ### Manage which vaults team members can grant access to Team members can only grant service accounts access to a vault if they have the appropriate permissions in the vault: | Account type | Permission | | --- | --- | | 1Password Teams | `Allow Managing` | | 1Password Business | `Manage Vault` | You can manage team members' permissions in vaults [with 1Password CLI](/docs/cli/grant-revoke-vault-permissions) or [on 1Password.com](https://support.1password.com/create-share-vaults-teams#manage-permissions). ### Manage service account access to vaults Team administrators can control service account access to 1Password vaults by turning access to a vault off or on. A vault's service account access setting applies to all service accounts. If you turn off service account access in a vault, existing service accounts will lose access to that vault and new service accounts can't be granted access. After you create a service account, you can't add additional vaults or edit any vault permissions it has. To turn service account access on or off for a vault: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Choose the vault you want to change service account access to. 3. Select **Manage**. 4. Under Service Account Access, select the toggle to turn access on or off. ## Get help ### If you need to change a service account's permissions or access After you create a service account, you can't give it access to additional vaults or [1Password Environments](/docs/environments), change its permissions in the vaults it can access, or change its ability to create new vaults. If you want to edit a service account's access or permissions, you'll need to create a new service account. You can [create a service account](/docs/service-accounts/get-started#create-a-service-account) on 1Password.com or with 1Password CLI. --- ## 1Password Service Accounts 1Password Service Accounts help automate secrets management in your applications and infrastructure without the need to deploy additional services. Service accounts work well for shared environments because they provide an authentication method for [1Password CLI](/docs/cli/) that isn't associated with an individual. You control which vaults and Environments are accessible and which actions the service account can perform. And you can see what items a service account accesses by creating a [usage report](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault). You can create up to 100 service accounts. :::tip Not sure if service accounts are for you? See the [secrets automation comparison table](/docs/secrets-automation#comparison). ::: ## Use cases You can use 1Password Service Accounts to accomplish a variety of tasks: - **Provision web services with secrets**: Use a service account to provision an account with a secret stored in 1Password. If a web service needs access to a database (and the credentials for the database are in 1Password), you can use a service account to provision an account with the needed secret and allow the web service to access the secret during test runs. - **Load secrets into CI/CD pipelines**: Use a service account to automatically access your secrets in continuous integration environments. If you've committed code and want to automatically run your CI/CD pipeline with credentials stored in a 1Password vault, you can use a service account to automatically access your secrets and use them for testing and deploying code while maintaining security without tying sensitive information to a personal user account. - **Automate secrets management**: Use service accounts to automate scripts to manage secrets. Using a service account helps you implement the principal of least privilege and avoid the limitations of personal accounts (for example, SSO and MFA requirements). - **Create a test environment**: Use a service account in a test environment while using Connect in production. Using a service account for your test environment allows you to create a similar test environment while keeping secrets or access compartmentalized. You can use service accounts to automatically access secrets in the test environment without having to set up Connect. - **Secure infrastructure secrets**: Use service accounts to make sure infrastructure secrets aren't tied to a personal user account. - **Streamline development workflows**: Use service accounts to securely share and manage infrastructure secrets to streamline development workflows. ## Get started Learn how to get started and how to create, manage, and integrate with service accounts. Get started --- ## Service account rate limits 1Password Service Accounts have hourly limits and daily limits. [Hourly limits](#hourly-limits) control the number of read and write actions a service account can perform within a 60-minute window. [Daily limits](#daily-limits) determine the total number of requests that all service accounts within a 1Password account can make in a 24-hour window. Some 1Password CLI commands make more than one request. You can use [`op service-account ratelimit`](/docs/cli/reference/management-commands/service-account#service-account-ratelimit) to get rate limit usage data for the service account currently set with the `OP_SERVICE_ACCOUNT_TOKEN` environment variable. To get information about a specific service account, specify a service account by its name or ID. ```bash op service-account ratelimit <service-account> #code-result TYPE ACTION LIMIT USED REMAINING RESET token write 1000 0 1000 N/A token read 10000 3 9997 59 minutes from now account read_write 50000 3 49997 23 hours from now ``` :::tip Learn which 1Password CLI commands [make multiple requests](/docs/service-accounts/use-with-1password-cli#commands-that-make-multiple-requests). ::: ## Hourly limits Service account tokens have hourly limits applied to both read and write actions independently. The 60-minute time window begins after 1Password receives the first request. Your 1Password account type determines the hourly limits. | Account type | Action | Limit | Period | Scope | | -------------------------------------------------- | ------ | ------ | ------ | ------------------------- | | [1Password Business](https://support.1password.com/explore/business/) | Read | 10,000 | 1 hour | Per service account token | | | Write | 1,000 | 1 hour | Per service account token | | 1Password, [1Password Families](https://support.1password.com/explore/families/), and [1Password Teams](https://support.1password.com/explore/team-admin/) | Read | 1,000 | 1 hour | Per service account token | | | Write | 100 | 1 hour | Per service account token | If you exceed the hourly limit, you'll receive the following error: ```text variant="bad" Error: [ERROR] (429) Too Many Requests: You've reached the maximum number of this type of requests this service account is allowed to make. Please retry in 59 minutes or try other requests. ``` :::tip If you hit an hourly limit, you can: - Wait for the 60-minute window to reset. - [Change your 1Password account type.](https://support.1password.com/change-account-type/) - [Contact 1Password support.](https://support.1password.com/contact/) - [Create a new service account.](/docs/service-accounts/get-started/) Hourly limits are scoped per service account token. ::: ## Daily limits 1Password has daily limits in place that determine the total number of requests that all service accounts can make over a 24-hour period. Your 1Password account type determines the daily limit. | Account type | Action | Limit | Period | Scope | | -------------------------------- | ---------- | ------ | -------- | --------------------- | | [1Password Business](https://support.1password.com/explore/business/) | Read/Write | 50,000 | 24 hours | Per 1Password account | | [1Password Teams](https://support.1password.com/explore/team-admin/) | Read/Write | 5,000 | 24 hours | Per 1Password account | | 1Password and [1Password Families](https://support.1password.com/explore/families/) | Read/Write | 1,000 | 24 hours | Per 1Password account | If you exceed the daily limit, you'll receive the following error: ```text variant="bad" Error: [ERROR] (429) Too Many Requests: You've reached the maximum number of this type of requests this 1Password account is allowed to make. Please retry in 23 hours and 59 minutes or try other requests. ``` :::tip If you hit a daily limit, you can: - Wait for the 24-hour window to reset. - [Change your 1Password account type.](https://support.1password.com/change-account-type/) - [Contact 1Password support.](https://support.1password.com/contact/) ::: --- ## 1Password Service Account security You can automate managing secrets in your apps and systems with [1Password Service Accounts](/docs/service-accounts/). No need for extra services. Explore the sections on this page to learn more about service account security. For information about 1Password security practices, visit the [1Password Security homepage](https://1password.com/security). ## Access control When creating a service account, you choose the vaults it can access and its level of access. The service account only returns information from vaults it can access. You can also give service accounts permission to create and manage vaults. ## Service accounts and token generation A service account is a type of user account that's meant for programmatic access. Service accounts differ from regular 1Password accounts in that you don't need to provide an email or an [account password](https://support.1password.com/1password-glossary#1password-account-password). When a regular user account creates a master key, the user must provide an email, a [Secret Key](https://support.1password.com/1password-glossary#secret-key), and an account password. When a service account user creates a master key, 1Password generates all the input. | Element | Regular user | Service account | |------------|--------------|-----------------| | Secret Key | Generated | Generated | | Password | User provided | Generated | 1Password uses the Secret Key and the password as part of the [two-secret key derivation (2SKD)](#2skd) process to create the following: - [Account Unlock Key (AUK)](#auk) - [Secure Remote Password (SRP)](#srp) After deriving these two items, 1Password discards the password used to create them. Each user, whether a regular user or a service account user, has a [personal keyset](#personal-keyset) that 1Password generates when you create the user account. The AUK encrypts the personal keyset, and 1Password uses the personal keyset to encrypt and decrypt vaults. A service account token is an authentication string that represents an SRPx object that's serialized and Base64 URL encoded. The service account token allows a service account to authenticate with 1Password CLI. 1Password creates the service account token by serializing the Account Unlock Key (AUK), Secure Remote Password (SRP), and the personal keyset into a [JSON Web Token (JWT) ](https://jwt.io/), then Base64 encoding it. See the following examples of a service account token encoded and decoded. **Encoded:** Encoded service account token: ```jwt ops_eyJlbWFpbCI6ImVqd2U2NHFtbHhocmlAMXBhc3N3b3Jkc2VydmljZWFjY291bnRzLmxjbCIsIm11ayI6eyJhbGciOiJBMjU2R0NNIiwiZXh0Ijp0cnVlLCJrIjoiTThWUGZJYzhWRWZUaGNNWExhS0NLRjhzTWg1Sk1ac1BBdHU5MmZRTmItbyIsImtleV9vcHMiOlsiZW5jcnlwdCIsImRlY3J5cHQiXSwia3R5Ijoib2N0Iiwia2lkIjoibXAifSwic2VjcmV0S2V5IjoiQTMtQzRaSk1OLVBRVFpUTC1IR0w4NC1HNjRNNy1LVlpSTi00WlZQNiIsInNycFgiOiI4NzBkNjdhOWU2MjY2MjVkOWUzNjg1MDc4MDRjOWMzMmU2NjFjNTdlN2U1NTg3NzgyOTFiZjI5ZDVhMjc5YWUxIiwic2lnbkluQWRkcmVzcyI6ImdvdGhhbS5iNWxvY2FsLmNvbTo0MDAwIiwidXNlckF1dGgiOnsibWV0aG9kIjoiU1JQZy00MDk2IiwiYWxnIjoiUEJFUzJnLUhTMjU2IiwiaXRlcmF0aW9ucyI6MTAwMDAwLCJzYWx0IjoiRk1SVVBpeXJONFhmXzhIb2g2WVJYUSJ9fQ ``` **Decoded:** Decoded service account token: ```json { "email": "ejwe64qmlxhri@1passwordserviceaccounts.lcl", "muk": { "alg": "A256GCM", "ext": true, "k": "M8VPfIc8VEfThcMXLaKCKF8sMh5JMZsPAtu92fQNb-o", "key_ops": [ "encrypt", "decrypt" ], "kty": "oct", "kid": "mp" }, "secretKey": "A3-C4ZJMN-PQTZTL-HGL84-G64M7-KVZRN-4ZVP6", "srpX": "870d67a9e626625d9e368507804c9c32e661c57e7e558778291bf29d5a279ae1", "signInAddress": "gotham.b5local.com:4000", "userAuth": { "method": "SRPg-4096", "alg": "PBES2g-HS256", "iterations": 100000, "salt": "FMRUPiyrN4Xf_8Hoh6YRXQ" }, "throttleSecret": { "seed": "ddc20da89d71ff640f36bb6c446c64d56a2123eb4e7bd9c89ce303075eea5780", "uuid": "TP4Z5ZB7IJABDPGIVSUZLY4T5A" }, "deviceUuid": "ay5shynibdyqisjz3j63b7uygy" } ``` :::info 1Password uses a unique string format to help code analyzers find accidental credential exposure. The format uses "`ops_`" as the token prefix. ::: The steps to create the token happen on your device (client-side); nothing sensitive goes to 1Password's servers. It's up to you to save and protect the service account token. ### Token rotation and revocation {#token-rotation} You can rotate or revoke service account tokens. You might want to revoke or rotate a service account token if a service account token became compromised or you need to comply with a security policy that requires regular token rotation. - [Learn how to revoke a service account token.](/docs/service-accounts/manage-service-accounts#revoke-token) - [Learn how to rotate a service account token.](/docs/service-accounts/manage-service-accounts#rotate-token) ## Security model The 1Password Service Account security model has the following guarantees: - A service account can only read items from vaults it has READ access to. - A service account can only update, delete, and create items for vaults it has WRITE access to. - The creator of a service account can only grant the service account access to vaults that the creator has access to. - You can't grant a service account access to vaults that have service accounts turned off, even if the creator of the service account has permissions to manage the vault. - Disabling service accounts for a vault removes access to that vault from all pre-existing service accounts. - By default, account [owners](https://support.1password.com/1password-glossary#owner) and [administrators](https://support.1password.com/1password-glossary#administrator) can create service accounts. - All owners and administrators can view service account details and delete service accounts, but they can't view the generated service account token. - Owners and administrators can [give other team members access](/docs/service-accounts/manage-service-accounts#manage-who-can-create-service-accounts) to create and manage their own service accounts. - Team members can only grant service accounts access to a vault if they have the `Manage Vault` permission for that vault. - A service account token associated with a deleted service account can't authenticate. - You can't add vault access to a generated service account after creation. - A service account can't create another service account. - A service account can't manage users. ## Terminology ##### Account Unlock Key {#auk} The Account Unlock Key (AUK) is a key derived from the [2SKD process](#2skd). It's used to decrypt a user's [personal keyset](#personal-keyset). It's derived from the user's account password and Secret Key. Previously known as the “Master Unlock Key”. ##### Personal keyset Each user account (whether a regular user or a service account) has a personal keyset that consists of a public and private key pair that's used to encrypt and decrypt vaults. ##### Secure Remote Password {#srp} The Secure Remote Password (SRP) is a key derived from the [2SKD process](#2skd). It's used for the Secure Remote Password protocol, which is a method for both a client and a server to authenticate each other without either revealing any secrets. ##### Service account token {#service-account-token} A service account token is an authentication string that grants a service account access to one or more 1Password vaults. You can use service account tokens to authenticate services and tools, such as the 1Password CLI. ##### Two-secret key derivation {#2skd} Two-secret key derivation (2SKD) is a type of key derivation function that uses two user secrets (the Account password and Secret Key) to derive two independent keys (the [Account Unlock Key](#auk) and the [Secure Remote Password](#srp)). ## Responsible disclosure 1Password requests you practice responsible disclosure if you discover a vulnerability. If you find a vulnerability in 1Password, [submit a report on HackerOne. ](https://hackerone.com/1password) --- ## Use service accounts with 1Password CLI You can use 1Password Service Accounts with 1Password CLI to manage vaults and items. See [supported commands](#supported-commands). ## Requirements Before you use service accounts with 1Password CLI, you need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - Install [1Password CLI](/docs/cli/get-started/). Service Accounts require 1Password CLI version 2.18.0 or later. - [Create a service account.](/docs/service-accounts/get-started#create-a-service-account) ## Get started To use a service account with 1Password CLI: 1. Set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to the service account token: **bash, sh, zsh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token> ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN <your-service-account-token> ``` **Powershell:** ```shell $Env:OP_SERVICE_ACCOUNT_TOKEN = "<your-service-account-token>" ``` 2. Run the following command to make sure the service account is configured: ```shell {9} op user get --me # code-result ID: <service-account-id> Name: <service-account-name> Email: <service-account-email> State: ACTIVE Type: SERVICE_ACCOUNT Created: 2 minutes ago Updated: 2 minutes ago Last Authentication: now ``` :::warning[caution] If you have 1Password CLI configured to work with [1Password Connect](/docs/connect/), the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables take precedence over `OP_SERVICE_ACCOUNT_TOKEN`. Clear the Connect environment variables to configure a service account instead. ::: ### Supported commands You can now run supported 1Password CLI commands authenticated as the service account: - [`op read`](/docs/cli/reference/commands/read/) - [`op inject`](/docs/cli/reference/commands/inject/) - [`op service-account ratelimit`](/docs/cli/reference/management-commands/service-account#service-account-ratelimit) - [`op run`](/docs/cli/reference/commands/run/) - [`op vault create`](/docs/cli/reference/management-commands/vault#vault-create) To use the following commands, you must specify a vault with the `--vault` flag if the service account has access to more than one vault: - [`op item`](/docs/cli/reference/management-commands/item/) - [`op document`](/docs/cli/reference/management-commands/document/) The following commands are only supported for vaults created by the service account: - [`op vault delete`](/docs/cli/reference/management-commands/vault#vault-delete) - [`op vault group grant`](/docs/cli/reference/management-commands/vault#vault-group-grant) - [`op vault user grant`](/docs/cli/reference/management-commands/vault#vault-user-grant) - [`op vault group revoke`](/docs/cli/reference/management-commands/vault#vault-group-revoke) - [`op vault user revoke`](/docs/cli/reference/management-commands/vault#vault-user-revoke) **Unsupported commands** When using a service account, the following commands aren't supported: - [`op connect`](/docs/cli/reference/management-commands/connect) - [`op group`](/docs/cli/reference/management-commands/group/) - [`op user provision`](/docs/cli/reference/management-commands/user#user-provision) - [`op user confirm`](/docs/cli/reference/management-commands/user#user-confirm) - [`op user suspend`](/docs/cli/reference/management-commands/user#user-suspend) - [`op user delete`](/docs/cli/reference/management-commands/user#user-delete) - [`op user recovery`](/docs/cli/reference/management-commands/user#user-recovery) - [`op events-api`](/docs/cli/reference/management-commands/events-api/) - [`op vault edit`](/docs/cli/reference/management-commands/vault#vault-edit) Although service accounts support some user, group, and vault management commands, we recommend against using them because a full provisioning workflow isn't supported: - [`op user get`](/docs/cli/reference/management-commands/user#user-get) - [`op user list`](/docs/cli/reference/management-commands/user#user-list) - [`op group get`](/docs/cli/reference/management-commands/group#group-get) - [`op group list`](/docs/cli/reference/management-commands/group#group-list) ### Commands that make multiple requests Service accounts have [hourly and daily limits](/docs/service-accounts/rate-limits) on the total number of requests the service account can make. You can sometimes reduce the number of requests made by passing a vault or item's [unique identifier (ID)](/docs/cli/reference#unique-identifiers-ids) instead of its name. 1Password CLI commands make one request unless otherwise noted. The following commands make more than one request: | Command | Total requests | Notes | | --- | --- | --- | | `op item list` | 1 + 1 per vault the service account has access to | To limit total requests to 3, list items in a specific vault using the `--vault` flag. Pass the vault's ID to further limit requests to 2. | | `op item get` | 3 reads | To reduce to 1 request, pass the item and vault IDs. | | `op item create` | 1 read and 1 write | To reduce to 1 request, pass the vault ID. | | `op item delete` | 5 reads and 1 write | To reduce the read requests by 1, pass the vault ID. | | `op item edit` | 5 reads and 1 write | To reduce the read requests by 1, pass the vault ID. | | `op read` | 3 reads | To reduce to 1 request, pass the item and vault IDs. | | `op vault delete` | 2 reads + 1 write | To reduce the read requests by 1, pass the vault ID. | | `op vault edit` | up to 3 writes | The number of requests may vary depending on how many changes are made with a single command. | | `op vault get` | 2 reads | To reduce the read requests by 1, pass the vault ID. | --- ## Use Connect with Ansible The [1Password Connect Ansible collection ](https://github.com/1Password/ansible-onepasswordconnect-collection) contains modules that allow you to interact with your 1Password Connect deployment from [Ansible ](https://docs.ansible.com/ansible/latest/getting_started/basic_concepts.html) playbooks. The modules communicate with the [Connect API](/docs/connect/api-reference/) to support managing 1Password vaults and items through create, read, update, and delete operations. ## Requirements You must complete the following requirements before you can use the 1Password Connect Ansible collection: - [Create and deploy a Connect server.](/docs/connect/get-started/) - Install [Ansible ](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) version 7.x or later. - Install [Ansible Core ](https://docs.ansible.com/core.html) version 2.14 or later. - Install [Python ](https://www.python.org/downloads/) version 3.8 or later. ## Get started Use the following instructions to get started with the 1Password Ansible collection: 1. [Install the 1Password collection.](#step-1) 2. [Use the 1Password collection in an Ansible playbook.](#step-2) 3. Explore the [example playbooks](#examples). ### Step 1: Install the collection {#step-1} Install the `onepassword.connect` collection from [Ansible Galaxy. ](https://galaxy.ansible.com/onepassword/connect) ```shell ansible-galaxy collection install onepassword.connect ``` :::info The 1Password Ansible collection is also available for the [Red Hat Ansible Automation Platform. ](https://www.redhat.com/en/technologies/management/ansible) ::: ### Step 2: Use the collection in an Ansible task {#step-2} Use the `onepassword.connect` collection in an Ansible task: 1. Add `onepassword.connect` to the task `collections`. ```yaml {2} title="playbook.yaml" collections: - onepassword.connect # Specify the 1Password collection ``` 2. Provide the [Connect server access token](/docs/connect/concepts#connect-server-access-token) using the token variable in the Ansible task or the OP_CONNECT_TOKEN environment variable. You must set this value in each Ansible task. It's [best practice](#sensitive-data) to use a local variable to provide the Connect server access token because it's [more secure. ](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_environment.html#working-with-language-specific-version-managers) The following example sets the `connect_token` variable to the Connect token value, then references it for the token field. ```yaml {2,7} title="playbook.yaml" vars: connect_token: "<connect-server-token>" # Set the Connect server access token collections: - onepassword.connect # Specify the 1Password collection tasks: - onepassword.connect.generic_item: token: "{{ connect_token }}" ``` 3. Provide the Connect server hostname, IP address, or URL through the hostname variable in the Ansible task or the OP_CONNECT_HOST environment variable. You must set this value in each Ansible task. ```yaml {2} title="playbook.yaml" environment: OP_CONNECT_HOST: <connect-host> # Set the Connect server hostname collections: - onepassword.connect # Specify the 1Password collection ``` ## Examples Explore the following examples to learn how to perform specific tasks: - [Create an item.](#create-item) - [Update an item.](#update-item) - [Find an item by name.](#find-item-by-name) - [Get the value of a field.](#get-field-value) ### Create an item {#create-item} The following example uses the [`generic_item` module](#generic-item) to create a 1Password item. It also creates the `Random Code` value with a custom `generator_recipe`. ```yaml title="playbook.yaml" - name: Create 1Password Secret hosts: localhost vars: connect_token: "<connect-server-token>" # Set the Connect server access token environment: OP_CONNECT_HOST: <connect-host> # Set the Connect server hostname collections: - onepassword.connect # Specify the 1Password collection tasks: - onepassword.connect.generic_item: token: "{{ connect_token }}" # Pass the Connect server access token variable vault_id: "<vault-id>" # Set the 1Password vault ID title: Club Membership state: present fields: - label: Codeword value: "hunter2" section: "Personal Info" field_type: concealed - label: Random Code generate_value: on_create # Generate the value on creation generator_recipe: length: 16 include_symbols: no no_log: true # Turn off logs to avoid logging sensitive data register: op_item # Note: register is Ansible syntax ``` ### Update an item {#update-item} The following example uses the [`generic_item` module](#generic-item) to update a 1Password item. It also sets the `generate_value` setting to `always`, which means 1Password generates a new value for the field each time you run the playbook. :::warning[caution] The update operation completely replaces the item matching the `title` or `uuid` field. You will lose any properties that you don't provide in the task definition. To avoid losing data, store the items created by Ansible in a vault that's scoped in a way that only the Connect server can access it. ::: ```yaml title="playbook.yaml" - name: Update a 1Password Secret hosts: localhost vars: connect_token: "<connect-server-token>" # Set the Connect server access token environment: OP_CONNECT_HOST: <connect-host> # Set the Connect server hostname OP_VAULT_ID: "<vault-id>" # Set the 1Password vault ID collections: - onepassword.connect # Specify the 1Password collection tasks: - onepassword.connect.generic_item: token: "{{ connect_token }}" # Pass the Connect server access token variable title: Club Membership # uuid: 1ff75fa9fexample -- or use an Item ID to locate an item instead state: present fields: - label: Codeword field_type: concealed - label: Dashboard Password generate_value: always # Generate a new value every time the playbook runs generator_recipe: # Provide a custom password recipe length: 16 include_symbols: no no_log: true # Turn off logs to avoid logging sensitive data ``` ### Find an item by name {#find-item-by-name} The following example uses the [`item_info` module](#item-info) to find a 1Password item by name. ```yaml title="playbook.yaml" hosts: localhost vars: connect_token: "<connect-server-token>" # Set the Connect server access token environment: OP_CONNECT_HOST: <connect-host> # Set the Connect server hostname collections: - onepassword.connect # Specify the 1Password collection tasks: - name: Find the item with the label "Staging Database" in the vault "Staging Env" item_info: token: "{{ connect_token }}" item: Staging Database vault: Staging Env no_log: true # Turn off logs to avoid logging sensitive data register: op_item ``` ### Get the value of a field {#get-field-value} The following example uses the [`field_info` module](#field-info) to get the value of a specific field in a 1Password item. ```yaml title="playbook.yaml" hosts: localhost vars: connect_token: "<connect-server-token>" # Set the Connect server access token environment: OP_CONNECT_HOST: <connect-host> # Set the Connect server hostname collections: - onepassword.connect # Specify the 1Password collection tasks: - name: Find a field labeled "username" in an item named "MySQL Database" in a specific vault field_info: token: "{{ connect_token }}" # Pass the Connect token variable item: MySQL Database field: username vault: <vault-id> # Set the 1Password vault ID no_log: true # Turn off logs to avoid logging sensitive data register: op_item - name: Print the field definition ansible.builtin.debug: msg: "{{ op_item.field }}" ``` ## Reference Refer to the following sections to learn about the available [variables](#variables) and [modules](#modules). ### Variables All [modules](#modules) support the following variable definitions. You can either explicitly define the value on the Ansible task or let Ansible fall back to an environment variable to use the same value across all tasks. | Module variable | Environment variable | Description | | --------------- | -------------------- | ------------------------------------------------------------ | | hostname | OP_CONNECT_HOST | Specifies the hostname, IP address, or URL where your Connect server is deployed. | | token | OP_CONNECT_TOKEN | Specifies the string value of your Connect server access token. | | vault_id | OP_VAULT_ID | (Optional) The UUID of a 1Password vault. It must be a vault the Connect server token has access to. | :::warning[caution] Module variables take precedence over environment variables. If you plan to use an environment variable, make sure the corresponding module variable is absent. ::: ### Modules The 1Password Ansible collection has the following modules: - [`generic_item` module](#generic-item) - [`item_info` module](#item-info) - [`field_info` module](#field-info) #### `generic_item` {#generic-item} You can use the `generic_item` module to create, update, and delete 1Password items. :::warning[State is important] The `generic_item` module follows [Ansible's `present`/`absent` state pattern. ](https://docs.ansible.com/ansible/2.8/user_guide/playbooks_best_practices.html#always-mention-the-state) Behavior when the state is `present` (`state: present`): - If the module can't find a matching item by its `uuid` or `title`, it creates a new item with the defined values. - If the module finds a matching item on the server, it completely replaces the old item with a new item defined by the playbook values. Behavior when the state is `absent` (`state: absent`): - If the module can't find the item by its `uuid` or `title`, no action is taken. - If the module finds an item matching the `uuid` or `title`, it deletes the item. Otherwise, no action is taken. ::: When you use the `generic_item` module to create or update a 1Password item, you can have 1Password generate a field's value. You can specify one of three settings for `generate_value`: | `generate_value` setting | Effect | | ------------------------ | ------------------------------------------------------------ | | `never` **(Default)** | Don't generate the field value. Use the `value` parameter instead. | | `on_create` | Generate the value when creating the field. | | `always` | Generate a new value for the field every time the playbook is run. Overwrites the `value` parameter. | The following example generates a value (with a custom recipe) for the `Random Code` field by using the `on_create` setting and supplying a custom `generator_recipe`. ```yaml {20-24} title="playbook.yaml" - name: Create 1Password Secret hosts: localhost vars: connect_token: "<connect-server-token>" # Set the Connect server access token environment: OP_CONNECT_HOST: <connect-host> # Set the Connect server hostname collections: - onepassword.connect # Specify the 1Password collection tasks: - onepassword.connect.generic_item: token: "{{ connect_token }}" # Pass the Connect token variable vault_id: "<vault-id>" # Set the 1Password vault ID (optional) title: Club Membership state: present fields: - label: Codeword value: "hunter2" section: "Personal Info" field_type: concealed - label: Random Code generate_value: on_create # Generate the field value on creation generator_recipe: # Provide a custom password recipe length: 16 include_digits: no no_log: true # Turn off logs to avoid logging sensitive data register: op_item ``` #### `item_info` {#item-info} Use the `item_info` module to search for or get information about a 1Password item (such as the fields or metadata). :::info When you search for an item, 1Password first searches for the `uuid` (if it's provided), then searches for the `title`. When searching for an item by its `title`, the module uses a case-sensitive, exact-match query. ::: #### `field_info` {#field-info} Use the `onepassword.connect.field_info` module to get the value of an item field. The `field_info` module first finds the item by title or UUID, then searches for the requested field by name. If you provide a `section`, the module only searches within that item section. If you don't provide a section, the field name must be unique within the item. The search method compares field names using the [`unicodedata.normalize` ](https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) function and the `NKFD` form. ## Best practices Consider the following best practices when using the 1Password Ansible collection. - [Turn off task logging.](#turn-off-logging) - [Avoid using environment variables for sensitive information.](#sensitive-data) ### Turn off task logging {#turn-off-logging} It's best practice to turn off task logging for any tasks that interact with 1Password Connect. Ansible might print sensitive information if `no_log` is unset or set to `false`. To turn off logging, set `no_log` to `true`: ```yaml {9} title="playbook.yaml" collections: - onepassword.connect # Specify the 1Password collection tasks: - name: Find the item with the label "Staging Database" in the vault "Staging Env" item_info: token: "{{ connect_token }}" # Pass the Connect token variable item: Staging Database vault: Staging Env no_log: true # Turn off logs to avoid logging sensitive data register: op_item ``` ### Avoid using environment variables for sensitive information {#sensitive-data} It's best practice to use a local variable to set sensitive information, such as the Connect server access token, because [Ansible environment variables ](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_environment.html) are normally passed in plain text. --- ## 1Password Connect Server API reference :::info If you're new to 1Password Secrets Automation and 1Password Connect Server, [learn how to get started with a Secrets Automation workflow](/docs/connect/get-started/). ::: You can use the Connect API to work with the vaults and items in your account, and to list API activity on a Connect server: - [List vaults](#list-vaults) - [Get vault details](#get-vault-details) - [List items](#list-items) - [Add an item](#add-an-item) - [Get item details](#get-item-details) - [Replace an item](#replace-an-item) - [Delete an item](#delete-an-item) - [Update a subset of item attributes](#update-a-subset-of-item-attributes) - [List files](#list-files) - [Get file details](#get-file-details) - [Get file content](#get-file-content) - [List API activity](#list-api-activity) To view the API in another tool, download the [1Password Connect API specification file (1.8.1)](https://i.1password.com/media/1password-connect/1password-connect-api_1.8.1.yaml). ## Requirements Before you can use the 1Password Connect Server API, you'll need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Set up a Secrets Automation workflow.](/docs/connect/get-started#step-1). - [Deploy 1Password Connect](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) in your infrastructure. ## Request headers Each request to the API has to be authenticated with an [access token](/docs/connect/manage-connect#manage-access-tokens). Provide it and specify the content type: ``` Authorization: Bearer <access_token> Content-type: application/json ``` ## List vaults ``` GET /v1/vaults ``` ### Path parameters No path parameters ### Query parameters Parameter Type Description `filter` string Filter the vault collection using SCIM-style filters. Vaults can only be filtered by `name`. Optional. For example: `name eq "Demo Vault"` ### Responses <dl> <dt>200</dt> <dd>Returns an array of vault names and IDs</dd> <dt>401</dt> <dd>Invalid or missing token</dd> </dl> ## Get vault details ``` GET /v1/vaults/{vaultUUID} ``` ### Path parameters {#get-vaults-vaultuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve items from. ### Query parameters {#get-vaults-vaultuuid-query-parameters} No query parameters. ### Responses {#get-vaults-vaultuuid-responses} <dl> <dt>200</dt> <dd>Returns a Vault object</dd> <dt>401</dt> <dd>Invalid or missing token</dd> <dt>403</dt> <dd>Unauthorized access</dd> <dt>404</dt> <dd>Vault not found</dd> </dl> ## List items ``` GET /v1/vaults/{vaultUUID}/items ``` ### Path parameters {#get-vaults-vaultuuid-items-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to get the details of. ### Query parameters {#get-vaults-vaultuuid-items-query-parameters} Parameter Type Description `filter` string Filter the item collection using SCIM-style filters . Items can only be filtered by `title` or `tag`. Optional. For example: `title eq "Example Item"` or `tag eq "banking"` ### Responses <dl> <dt>200</dt> <dd>Returns an array of Item objects that don't include sections and fields</dd> <dt>401</dt> <dd>Invalid or missing token</dd> <dt>404</dt> <dd>Vault not found</dd> </dl> ## Add an item ``` POST /v1/vaults/{vaultUUID}/items ``` The request must include a FullItem object, containing the information to create the item. For example: ```json { "vault": { "id": "ftz4pm2xxwmwrsd7rjqn7grzfz" }, "title": "Secrets Automation Item", "category": "LOGIN", "tags": [ "connect", "\ud83d\udc27" ], "sections": [ { "label": "Security Questions", "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" } ], "fields": [ { "value": "wendy", "purpose": "USERNAME" }, { "purpose": "PASSWORD", "generate": true, "recipe": { "length": 55, "characterSets": [ "LETTERS", "DIGITS" ] } }, { "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "CONCEALED", "generate": true, "label": "Recovery Key" }, { "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "STRING", "generate": true, "label": "Random Text" }, { "type": "URL", "label": "Example", "value": "https://example.com" } ] } ``` Parameter Type Description `title` string The title of the item. `vault` object An object containing an `id` property whose value is the UUID of the vault the item is in. `category` string The category of the item. One of: <section> `"LOGIN"` `"PASSWORD"` `"API_CREDENTIAL"` `"SERVER"` `"DATABASE"` `"CREDIT_CARD"` `"MEMBERSHIP"` `"PASSPORT"` `"SOFTWARE_LICENSE"` `"OUTDOOR_LICENSE"` `"SECURE_NOTE"` `"WIRELESS_ROUTER"` `"BANK_ACCOUNT"` `"DRIVER_LICENSE"` `"IDENTITY"` `"REWARD_PROGRAM"` `"EMAIL_ACCOUNT"` `"SOCIAL_SECURITY_NUMBER"` `"MEDICAL_RECORD"` `"SSH_KEY"` </section> You can't create items using the "CUSTOM" or "DOCUMENT" categories. `urls` array Array of URL objects containing URLs for the item. `favorite` boolean Mark the item as a favorite. `tags` string An array of strings of the tags assigned to the item. `fields` array An array of Field objects of the fields to include with the item. `sections` array An array of Section objects of the sections to include with the item. ### Path parameters {#post-vaults-vaultuuid-items-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to create an item in. ### Query parameters {#post-vaults-vaultuuid-items-query-parameters} No query parameters. ### Responses <dl> <dt>200</dt> <dd>Returns Item object containing the new item</dd> <dt>400</dt> <dd>Unable to create item due to invalid input</dd> <dt>401</dt> <dd>Invalid or missing token</dd> <dt>403</dt> <dd>Unauthorized access</dd> <dt>404</dt> <dd>Item not found</dd> </dl> ## Get item details ``` GET /v1/vaults/{vaultUUID}/items/{itemUUID} ``` ### Path parameters {#get-vaults-vaultuuid-items-itemuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve the item from. `itemUUID` string The UUID of the item to retrieve. ### Query parameters {#get-vaults-vaultuuid-items-itemuuid-query-parameters} No query parameters. ### Responses {#get-vaults-vaultuuid-items-itemuuid-responses} <dl> <dt>200</dt> <dd>Returns an Item object</dd> <dt>401</dt> <dd>Invalid or missing token</dd> <dt>403</dt> <dd>Unauthorized access</dd> <dt>404</dt> <dd>Item not found</dd> </dl> ## Replace an item ``` PUT /v1/vaults/{vaultUUID}/items/{itemUUID} ``` ### Path parameters {#put-vaults-vaultuuid-items-itemuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve the item from. `itemUUID` string The UUID of the item to replace. ### Query parameters {#put-vaults-vaultuuid-items-itemuuid-query-parameters} No query parameters. ### Responses {#put-vaults-vaultuuid-items-itemuuid-responses} <dl> <dt>200</dt> <dd>Returns an Item object</dd> <dt>400</dt> <dd>Unable to create item due to invalid input</dd> <dt>401</dt> <dd>Invalid or missing token</dd> <dt>403</dt> <dd>Unauthorized access</dd> <dt>404</dt> <dd>Item not found</dd> </dl> ## Delete an item ``` DELETE /v1/vaults/{vaultUUID}/items/{itemUUID} ``` ### Path parameters {#delete-vaults-vaultuuid-items-itemuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve the item from. `itemUUID` string The UUID of the item to delete. ### Query parameters {#delete-vaults-vaultuuid-items-itemuuid-query-parameters} No query parameters. ### Responses {#delete-vaults-vaultuuid-items-itemuuid-responses} <dl> <dt>204</dt> <dd>Successfully deleted an item</dd> <dt>401</dt> <dd>Invalid or missing token</dd> <dt>403</dt> <dd>Unauthorized access</dd> <dt>404</dt> <dd>Item not found</dd> </dl> ## Update a subset of item attributes ``` PATCH /v1/vaults/{vaultUUID}/items/{itemUUID} ``` Applies an `add`, `remove`, or `replace` operation on an item or the fields of an item. Uses the [RFC6902 JSON Patch](https://tools.ietf.org/html/rfc6902) document standard. Parameter Type Description `op` string The kind of operation to perform. One of: `add` `remove` `replace` `path` string An RFC6901 JSON Pointer to the item, an item attribute, an item field by field ID, or an item field attribute. For example: `"/fields/vy09gd8EXAMPLE/label"` `value` any The new value to apply at the path. ### Path parameters {#patch-vaults-vaultuuid-items-itemuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault the item is in. `itemUUID` string The UUID of the item to update. ### Query parameters {#patch-vaults-vaultuuid-items-itemuuid-query-parameters} No query parameters. ### Responses {#patch-vaults-vaultuuid-items-itemuuid-responses} <dl> <dt>200</dt> <dd>Returns an Item object of the updated item.</dd> <dt>401</dt> <dd>Invalid or missing token</dd> <dt>403</dt> <dd>Unauthorized access</dd> <dt>404</dt> <dd>Item not found</dd> </dl> ## List files ``` GET /v1/vaults/{vaultUUID}/items/{itemUUID}/files ``` ### Path parameters {#get-vaults-vaultuuid-items-itemuuid-files-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to get the details of. `itemUUID` string The UUID of the item to retrieve. ### Query parameters {#get-vaults-vaultuuid-items-itemuuid-files-query-parameters} Parameter Type Description `inline_content` boolean Whether to return the Base-64 encoded file content. The file size must be less than `OP_MAX_INLINE_FILE_SIZE_KB`, or 100 kilobytes if the file size isn't defined. Optional. ### Responses {#get-vaults-vaultuuid-items-itemuuid-files-responses} <dl> <dt>200</dt> <dd>Returns an array of File objects</dd> <dt>401</dt> <dd>Invalid or missing token</dd> <dt>404</dt> <dd>Item not found</dd> <dt>413</dt> <dd>File too large to display inline</dd> </dl> ## Get File details ``` GET /v1/vaults/{vaultUUID}/items/{itemUUID}/files/{fileUUID} ``` ### Path parameters {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve the item from. `itemUUID` string The UUID of the item to retrieve the file from. `fileUUID` string The UUID of the file to retrieve. ### Query parameters {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-query-parameters} Parameter Type Description `inline_content` boolean Whether to return the Base-64 encoded file content. The file size must be less than `OP_MAX_INLINE_FILE_SIZE_KB`, or 100 kilobytes if the file size isn't defined. Optional. ### Responses {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-responses} <dl> <dt>200</dt> <dd>Returns a File object</dd> <dt>401</dt> <dd>Invalid or missing token</dd> <dt>403</dt> <dd>Unauthorized access</dd> <dt>404</dt> <dd>File not found</dd> <dt>413</dt> <dd>File too large to display inline</dd> </dl> ## Get file content ``` GET /v1/vaults/{vaultUUID}/items/{itemUUID}/files/{fileUUID}/content ``` ### Path parameters {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-content-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve the item from. `itemUUID` string The UUID of the item to retrieve the file from. `fileUUID` string The UUID of the file to retrieve. ### Query parameters {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-content-query-parameters} No query parameters. ### Responses {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-content-responses} <dl> <dt>200</dt> <dd>Returns the content of the file</dd> <dt>401</dt> <dd>Invalid or missing token</dd> <dt>403</dt> <dd>Unauthorized access</dd> <dt>404</dt> <dd>File not found</dd> </dl> ## List API activity ``` GET /v1/activity ``` Retrieve a list of API Requests that have been made. ### Query parameters {#get-activity-query-parameters} Parameter Type Description `limit` integer How many API Events should be retrieved in a single request. Optional. `offset` integer How far into the collection of API Events should the response start. Optional. ## Server Heartbeat ``` GET /heartbeat ``` Simple "ping" endpoint to check whether server is active. ### Query parameters {#get-heartbeat-query-parameters} No query parameters. ### Responses {#get-heartbeat-responses} <dl> <dt>200</dt> <dd>Returns a `text/plain` response with a single "."</dd> </dl> ## Server Health ``` GET /health ``` Query the state of the server and its service dependencies. ### Query parameters No query parameters. ### Responses {#get-heartbeat-responses} <dl> <dt>200</dt> <dd>Returns a Server Health object</dd> </dl> ## Metrics ``` GET /metrics ``` Returns Prometheus metrics collected by the server. ### Query parameters No query parameters. ### Responses {#get-heartbeat-responses} <dl> <dt>200</dt> <dd>Returns a plaintext list of Prometheus metrics. See the Prometheus documentation for specifics.</dd> </dl> ## Response object models ### APIRequest object Parameter Type Description `requestID` string The UUID for the request. `timestamp` dateTime Date and time of the request. `action` string The action taken. One of: `"READ"` `"CREATE"` `"UPDATE"` `"DELETE"` `result` string The result of the action. One of: `"SUCCESS"` `"DENY"` `actor` object An Actor object. `resource` object A Resource object. #### APIRequest: Actor object Parameter Type Description `id` string The UUID of the Connect server that made the request. `account` string The UUID of the 1Password account the request went to. `jti` string The UUID of the access token used to authenticate the request. `userAgent` string The user agent string specified in the request. `ip` string The IP address the request originated from. #### APIRequest: Resource object Parameter Type Description `type` string The resource requested. One of: `"ITEM"` `"VAULT"` `vault` object An object containing an `id` property with the value of the UUID of the vault requested. `item` object An object containing an `id` property with the value of the UUID of the item requested. `itemVersion` integer The version of the item. ### ErrorResponse object ```json { status: 401, message: "Invalid or missing token" } ``` Parameter Type Description `status` integer The HTTP status code. `message` string A message detailing the error. ### Vault object ```json { "id": "ytrfte14kw1uex5txaore1emkz", "name": "Demo", "attributeVersion": 1, "contentVersion": 72, "items": 7, "type": "USER_CREATED", "createdAt": "2021-04-10T17:34:26Z", "updatedAt": "2021-04-13T14:33:50Z" } ``` Parameter Type Description `id` string The UUID of the vault. `name` string The name of the vault. `description` string The description for the vault. `attributeVersion` integer The version of the vault metadata. `contentVersion` integer The version of the vault contents. `items` integer Number of active items in the vault. `type` string The type of vault. One of: `"EVERYONE"`: The team Shared vault. `"PERSONAL"`: The Private vault for the Connect server. `"USER_CREATED"`: A vault created by a user. `createdAt` dateTime Date and time when the vault was created. `updatedAt` dateTime Date and time when the vault or its contents were last changed. ### Item object ```json { "id": "2fcbqwe9ndg175zg2dzwftvkpa", "title": "Secrets Automation Item", "tags": [ "connect", "\ud83d\udc27" ], "vault": { "id": "ftz4pm2xxwmwrsd7rjqn7grzfz" }, "category": "LOGIN", "sections": [ { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562", "label": "Security Questions" } ], "fields": [ { "id": "username", "type": "STRING", "purpose": "USERNAME", "label": "username", "value": "wendy" }, { "id": "password", "type": "CONCEALED", "purpose": "PASSWORD", "label": "password", "value": "mjXehR*uCj!aoe!iktt9KMtWb", "entropy": 148.0838165283203, "passwordDetails": { "entropy": 148, "generated": true, "strength": "FANTASTIC", "history": [ "U-Trxf98hT_GTgNmA.a!pQp3U", "_ciCJpYuCB*E7@oRTto4JB4.3" ] } }, { "id": "notesPlain", "type": "STRING", "purpose": "NOTES", "label": "notesPlain" }, { "id": "a6cvmeqakbxoflkgmor4haji7y", "type": "URL", "label": "Example", "value": "https://example.com" }, { "id": "boot3vsxwhuht6g7cmcx4m6rcm", "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "CONCEALED", "label": "Recovery Key", "value": "s=^J@GhHP_isYP>LCq?vv8u7T:*wBP.c" }, { "id": "axwtgyjrvwfp5ij7mtkw2zvijy", "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "STRING", "label": "Random Text", "value": "R)D~KZdV!8?51QoCibDUse7=n@wKR_}]" } ], "files": [ { "id": "6r65pjq33banznomn7q22sj44e", "name": "testfile.txt", "size": 35, "content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/6r65pjq33banznomn7q22sj44e/content", }, { "id": "oyez5gf6xjfptlhc3o4n6o6hvm", "name": "samplefile.png", "size": 296639, "content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/oyez5gf6xjfptlhc3o4n6o6hvm/content", } ], "createdAt": "2021-04-10T17:20:05.98944527Z", "updatedAt": "2021-04-13T17:20:05.989445411Z" } ``` Parameter Type Description `id` string The UUID of the item. `title` string The title of the item. `vault` object An object containing an `id` property whose value is the UUID of the vault the item is in. `category` string The category of the item. One of: <section> `"LOGIN"` `"PASSWORD"` `"API_CREDENTIAL"` `"SERVER"` `"DATABASE"` `"CREDIT_CARD"` `"MEMBERSHIP"` `"PASSPORT"` `"SOFTWARE_LICENSE"` `"OUTDOOR_LICENSE"` `"SECURE_NOTE"` `"WIRELESS_ROUTER"` `"BANK_ACCOUNT"` `"DRIVER_LICENSE"` `"IDENTITY"` `"REWARD_PROGRAM"` `"DOCUMENT"` `"EMAIL_ACCOUNT"` `"SOCIAL_SECURITY_NUMBER"` `"MEDICAL_RECORD"` `"SSH_KEY"` </section> You can't create items using the "CUSTOM" or "DOCUMENT" categories. `urls` array Array of URL objects containing URLs for the item. `favorite` boolean Whether the item is marked as a favorite. `tags` array An array of strings of the tags assigned to the item. `version` integer The version of the item. `createdAt` dateTime Date and time when the item was created. `updatedAt` dateTime Date and time when the vault or its contents were last changed. `lastEditedBy` string UUID of the account that last changed the item. #### Item: Field object ```json { "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "STRING", "generate": true, "label": "Random Text" } ``` Parameter Type Description `purpose` or `type` string Use `purpose` for the username, password, and notes fields. Possible values: <section> `"USERNAME"` `"PASSWORD"` `"NOTES"` </section> Use `type` for all other fields. Possible values are: <section> `"STRING"` `"EMAIL"` `"CONCEALED"` `"URL"` `"OTP"` (format: `otpauth://`) `"DATE"` (format: `YYYY-MM-DD`) `"MONTH_YEAR"` (format: `YYYYMM` or `YYYY/MM`) `"MENU"` </section> `value` string The value to save for the field. You can specify a `generate` field instead of `value` to create a password or other random information for the value. `generate` boolean Generate a password and save in the value for the field. By default, the password is a 32-characters long, made up of letters, numbers, and symbols. To customize the password, include a `recipe` field. `recipe` object A GeneratorRecipe object. `section` object An object containing the UUID of a section in the item. #### Item: File object ```json { "id": "6r65pjq33banznomn7q22sj44e", "name": "testfile.txt", "size": 35, "content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/6r65pjq33banznomn7q22sj44e/content", "content": "VGhlIGZ1dHVyZSBiZWxvbmdzIHRvIHRoZSBjdXJpb3VzLgo=", "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, } ``` Name Type Description `id` string The UUID of the file. `name` string The name of the file. `size` integer The size of the file in bytes. `content_path` string The path to download the contents of the file. `content` string The Base64-encoded contents of the file, if `inline_files` is set to `true`. `section` object An object containing the UUID of a section in the item. #### Item: GeneratorRecipe object The recipe is used in conjunction with the "generate" property to set the character set used to generate a new secure value. ```json { "length": 55, "characterSets": [ "LETTERS", "DIGITS" ] } ``` Name Type Description `length` integer The length of the password to generate. Optional. `characterSets` array An array containing of the kinds of characters to include. Optional. Possible values: `"LETTERS"` `"DIGITS"` `"SYMBOLS"` `excludeCharacters` string A list of all characters that should be excluded from generated passwords. Optional. #### Item: PasswordDetails object ```json { "entropy": 148, "generated": true, "strength": "FANTASTIC", "history": [ "U-Trxf98hT_GTgNmA.a!pQp3U", "_ciCJpYuCB*E7@oRTto4JB4.3" ] } ``` Name Type Description `entropy` integer The unpredictability of the password, measured in bits. `generated` boolean Whether the password was generated using the password generator. `strength` string The strength of the password. One of: `"TERRIBLE"` `"WEAK"` `"FAIR"` `"GOOD"` `"VERY_GOOD"` `"EXCELLENT"` `"FANTASTIC"` `history` array An array of strings containing the previous passwords of the item. #### Item: Section object ```json { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" "label": "Security Questions", } ``` Name Type Description `id` string A unique identifier for the section. `label` string The label for the section. #### Item: URL object ```json { "label": "website", "primary": true, "href": "https://example.com" } ``` Name Type Description `label` string The label for the URL. `primary` boolean Whether this is the primary URL for the item. `href` string The address. ### Server Health object ```json { "name": "1Password Connect API", "version": "1.2.1", "dependencies": [ { "service": "sync", "status": "TOKEN_NEEDED" }, { "service": "sqlite", "status": "ACTIVE", "message": "Connected to ~/1password.sqlite" } ] } ``` Name Type Description `name` string Name of the server `version` string Version info of the Connect server `dependencies` array An array of Service Dependencies. #### Server Health: Dependency object {#server-health-dependency-object} Name Type Description `service` string Name of the dependency `status` string The service's reported status `message` string Extra information about the dependency's status. Optional. --- ## AWS ECS Fargate # Deploy 1Password Connect Server on AWS ECS Fargate with CloudFormation 1Password Connect works with [AWS Fargate ](https://docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate.html). AWS Fargate lets you leverage Amazon Elastic Container Service (ECS) to run containers without the need to manage clusters. ## Requirements Before you can use 1Password CLI with your Connect server, you must: - [Sign up for 1Password](https://1password.com/pricing/password-manager). - [Create a 1Password Connect server](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) in your infrastructure. - Sign up with [AWS Fargate ](https://docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate.html). ## Example You can use 1Password's [example CloudFormation template (`connect.yaml`) ](https://github.com/1Password/connect/blob/main/examples/aws-ecs-fargate/connect.yaml) as a starting place for deploying Connect on AWS Fargate. The example [CloudFormation template ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-whatis-concepts.html#cfn-concepts-templates) creates the necessary networking resources, ECS resources, rules, groups, and policies. See [Resources](#resources) for more details. The result is a publicly accessible hostname that routes requests to a 1Password Connect Server deployment running in AWS Fargate. :::tip You can also use this example CloudFormation file to deploy into an existing [AWS virtual private cloud (VPC) ](https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html) or an existing [Amazon Elastic Container (AWS ECS) ](https://docs.aws.amazon.com/ecs/) cluster. You can modify it using a text editor or using Amazon's [CloudFormation Designer ](https://console.aws.amazon.com/cloudformation/designer) tool. ::: ### Resources The example CloudFormation template creates the following network resources: - A virtual private cloud (VPC) - Two public subnets - An [Internet gateway ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-internetgateway.html) - An [Application Load Balancer (ALB) ](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) The example CloudFormation template creates the following ECS resources: - An [ECS cluster ](https://docs.aws.amazon.com/AmazonECS/latest/userguide/clusters-concepts.html) - Two [task definitions ](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-tasks-services.html) - A `1password/connect-api` container - A `1password/connect-sync` container ## Get started To use the example `connect.yaml` file to deploy a Connect server on AWS Fargate (using CloudFormation): 1. [Start the **AWS Create Stack** wizard. ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-create-stack.html#cfn-using-console-initiating-stack-creation) 2. Select the example [`connect.yaml` file ](https://github.com/1Password/connect/blob/main/examples/aws-ecs-fargate/connect.yaml) as the stack template. See [Selecting a stack template ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-using-console-create-stack-template.html). 3. Provide a Base64 URL encoded version of your Connect server's `1password-credentials.json` file. When importing this CloudFormation template, it prompts you to provide a Base64 URL encoded version of the `1password-credentials.json`. You can generate this encoded value with the following shell command: ```shell cat 1password-credentials.json | base64 | tr '/+' '_-' | tr -d '=' | tr -d '\n' ``` --- ## Use 1Password CLI with a Connect server You can use 1Password CLI with a [Connect server](/docs/connect/) to provision secrets and retrieve items on the command line. ## Requirements Before you can use 1Password CLI with a Connect server, you must: - [Sign up for 1Password](https://1password.com/pricing/password-manager). - [Deploy 1Password Connect](/docs/connect/get-started#step-2-deploy-a-1password-connect-server). - Make a Connect server accessible to your production environment. - [Install 1Password CLI in your production environment.](/docs/cli/install-server/) - Set the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables to a Connect server's credentials in your production environment. ## Get started After you complete the requirement steps, you can use the following 1Password CLI commands with a Connect server: - [`op run`](/docs/cli/reference/commands/run/) - [`op inject`](/docs/cli/reference/commands/inject/) - [`op read`](/docs/cli/reference/commands/read/) - [`op item get --format json`](/docs/cli/reference/management-commands/item#item-get) Vist the command documentation for more information. ## Continuous integration (CI) environments You can also use 1Password CLI with a Connect server in a continuous integration (CI) pipeline. 1Password CLI allows you to use [secret references](/docs/cli/secret-references/) in place of plaintext secrets in code. You can configure a CI environment to pass different sets of secrets for different environments. Secret references work well within infrastructure as code tools and CI configurations because you can define them alongside other configurations. ### GitLab CI example The following code block shows an example GitLab CI configuration file that implements a MySQL service. See [GitLabs `.gitlab-ci.yml` documentation ](https://docs.gitlab.com/ee/ci/yaml/). ```yaml title=".gitlab-ci.yml" services: - mysql variables: # Configure mysql service (https://hub.docker.com/_/mysql/) MYSQL_DATABASE: op://prod/mysql/database MYSQL_USERNAME: op://prod/mysql/username MYSQL_PASSWORD: op://prod/mysql/password connect: image: mysql script: - echo "SELECT 'OK';" | op run -- mysql --user="$MYSQL_USERNAME" --password="$MYSQL_PASSWORD" --host=mysql "$MYSQL_DATABASE" ``` To authenticate 1Password CLI in the CI pipeline, add the OP_CONNECT_HOST and OP_CONNECT_TOKEN environment variables to a CI configuration file. The presence of these environment variables tells 1Password CLI to use the Connect server to fetch secrets. The following code block expands the GitLab CI example to include the Connect environment variables. ```yaml [{ "color": "bitsblue", "lineNo": 10, "substr": "OP_CONNECT_HOST" }, { "color": "lagoon", "lineNo": 11, "substr": "OP_CONNECT_TOKEN" }] title=".gitlab-ci.yml" services: - mysql variables: # Configure mysql service (https://hub.docker.com/_/mysql/) MYSQL_DATABASE: op://prod/mysql/database MYSQL_USERNAME: op://prod/mysql/username MYSQL_PASSWORD: op://prod/mysql/password # Configure 1Password CLI to use Connect OP_CONNECT_HOST: <Connect host URL>:8080 OP_CONNECT_TOKEN: token connect: image: mysql script: - echo "SELECT 'OK';" | mysql --user="$MYSQL_USERNAME" --password="$MYSQL_PASSWORD" --host=mysql "$MYSQL_DATABASE" ``` ## Learn more ### [Replace plaintext secrets with secret references](/docs/cli/secret-references/) Learn how to create and use secret references to avoid putting plaintext secrets in code. ### [Load secrets into the environment](/docs/cli/secrets-environment-variables/) Learn how to source secrets from the environment into your applications. ### [Load secrets into config files](/docs/cli/secrets-config-files/) Learn how to load secrets automatically into config files without putting any plaintext secrets in code. --- ## Connect concepts Learn about the concepts involved with 1Password Connect. ## Connect servers {#servers} A Connect server is a tool you can deploy in your network that allows you to manage and sync 1Password items from within your infrastructure. ## Credentials {#credentials} There are two important pieces of information for authenticating Connect servers: - The `1password-credentials.json` file - The Connect server access token ### `1password-credentials.json` When you create a Connect server, a credentials file named `1password-credentials.json` is generated uniquely for that Connect server. It contains all the information you need to [deploy the Connect server](/docs/connect/get-started#step-2-deploy-a-1password-connect-server). ### Connect server access token A Connect server access token is an authentication string that allows the Connect server to authenticate with 1Password services, such as the [Connect REST API](/docs/connect/api-reference/). When you create a Connect server, you select the vaults that it can access. Connect servers can only access the vaults you explicitly allow them to access through a Connect server token. Each Connect server can have one or more access tokens, which allows for more fine-tuned [access control](/docs/connect/security#access-control). Connect server access tokens can only access information in the vaults you grant them access to. This allows you more granular control over the vaults a Connect server deployment can access. For example, you can grant a Connect token access to a specific subset of the vaults the Connect server has access to. Learn more about [how to manage access tokens](/docs/connect/manage-connect#manage-access-tokens). Learn more about [1Password Connect server security](/docs/connect/security/). ## Connect containers {#containers} Each Connect server deployment consists of two Docker containers running in the same network: - The [Connect sync container](#connect-sync-container) - The [Connect API container](#connect-api-container) Both containers require a shared volume to store an encrypted copy of your data. Learn more about [configuring your Connect server](/docs/connect/server-configuration/). ### Connect sync container The Connect sync container keeps information on the Connect server in sync with 1Password.com. View it on Docker Hub: [`1password/connect-sync`](https://hub.docker.com/r/1password/connect-sync). ### Connect API container The Connect API container serves [Connect REST API](/docs/connect/api-reference/). View it on Docker Hub: [`1password/connect-api`](https://hub.docker.com/r/1password/connect-api). ## Environment variables {#environment-variables} Connect servers have a collection of environment variables you can use to provide information about the Connect server to integrations, such as [1Password CLI](/docs/connect/cli/) or [CI/CD pipeline tools](/docs/ci-cd/). These environment variables are distinct from the [configuration environment variables](/docs/connect/server-configuration#environment-variables). | Environment variable | Description | Example | | -------------------- | ------------------------------------------------------------ | ----------------------- | | `OP_CONNECT_HOST` | Specifies the hostname, IP address, or URL where your Connect server is deployed. | `http://localhost:8080` | | `OP_CONNECT_TOKEN` | Specifies the string value of your Connect server token. | N/A | --- ## Get started with a 1Password Connect server 1Password Connect servers are a type of [Secrets Automation workflow](/docs/secrets-automation/) that allows you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure. ## Requirements Before you can create a 1Password Secrets Automation workflow as a Connect server, make sure you complete the prerequisite tasks. The tasks vary depending on how you plan to deploy. **Docker:** - [Sign up for a 1Password account](https://1password.com/pricing/password-manager). - [Create a vault](https://support.1password.com/create-share-vaults/) for the Connect server to access. Connect servers can't access your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault, or your default [Shared](https://support.1password.com/1password-glossary#shared-vault) vault. - Make sure you belong to [a group with permission to manage Secrets Automation](/docs/connect/manage-connect/). - Make sure you have a deployment environment for Docker. You can use a cloud service provider or your local machine. **Kubernetes:** - [Sign up for a 1Password account](https://1password.com/pricing/password-manager). - [Create a vault](https://support.1password.com/create-share-vaults/) for the Connect server to access. Connect servers can't access your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault, or your default [Shared](https://support.1password.com/1password-glossary#shared-vault) vault. - Make sure you belong to [a group with permission to manage Secrets Automation](/docs/connect/manage-connect/). - Make sure you have a deployment environment for Kubernetes with [kubectl ](https://kubernetes.io/docs/tasks/tools/install-kubectl/), and [Helm ](https://helm.sh/) installed. You can use a cloud service provider or your local machine. ## Deployment Use the following instructions to deploy a 1Password Connect Server. ### Step 1: Create a Secrets Automation workflow {#step-1} You can create a Connect server Secrets Automation workflow through the 1Password.com dashboard or 1Password CLI. Following these instructions creates: - A `1password-credentials.json` file. It contains the credentials necessary to deploy 1Password Connect Server. - An access token. Use this in your applications or services to authenticate with the [Connect REST API](/docs/connect/api-reference/). You can [issue additional tokens later](/docs/connect/manage-connect#create-a-token). **1Password.com:** 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Open the [Secrets Automation workflow creation wizard](https://start.1password.com/developer-tools/infrastructure-secrets/connect). Or, navigate to **Developer** > **Directory**, select **Other** under Infrastructure Secrets Management, then select **Create a Connect server**. 3. Follow the onscreen instructions to create a Secrets Automation environment, set up your first access token, and deploy a Connect server. Make sure to save your credentials file and token in 1Password. You can find your new Secrets Automation workflow under "Connect servers" on the [**Developer**](https://start.1password.com/developer-tools/active) page. **1Password CLI:** You can use the [1Password CLI](https://1password.com/downloads/command-line) [`op connect` command](/docs/cli/reference/management-commands/connect/) to set up a Secrets Automation workflow with a Connect server. 1. Make sure you have the latest version of [1Password CLI](/docs/cli/get-started/) on your machine. 2. Switch to the directory where you want to create the `1password-credentials.json`. Creating a Connect server automatically generates the `1password-credentials.json` file in the current directory. This file contains the credentials you'll need to deploy the Connect server. If a `1password-credentials.json` file already exists in the current directory, 1Password CLI will ask if you want to overwrite it. 3. Create a Connect server and grant it access to a shared vault using the [`op connect server create` command](/docs/cli/reference/management-commands/connect#connect-server-create). ```shell op connect server create <serverName> --vaults <vaultName> ``` :::tip Omit the `--vaults` flag to create a Connect server without granting it access to a vault. You can grant the Connect server access to shared vaults later using the [`op connect vault grant` command](/docs/cli/reference/management-commands/connect#connect-vault-grant). ::: If the Connect server or vault name contains one or more spaces, enclose the name in quotation marks (for example, `“My Server Name”`). You don't need to enclose strings in quotation marks if they don't contain spaces (for example, `myServerName`). ``` op connect server create "My Server Name" --vault "My Vault Name" ``` 4. Create a token for the Connect server using the [`op connect token create` command](/docs/cli/reference/management-commands/connect#connect-token). ```shell op connect token create <tokenName> --server <serverName|serverID> --vault <vaultName|vaultID> ``` :::tip Looking up a Connect server by its ID is more efficient than using the Connect server's name. See [Unique identifiers (IDs)](/docs/cli/reference#unique-identifiers-ids). You can find the ID of a Connect server by running [`op connect server list`](/docs/cli/reference/management-commands/connect#connect-server-list). ::: If successful, 1Password CLI returns a token string that you can use in your applications or services to authenticate with the [Connect server REST API](/docs/connect/api-reference/). You can [issue additional tokens later.](/docs/connect/manage-connect#create-a-token) 5. Save the token in 1Password so you don't lose it. You can have multiple tokens for the same Connect server but each Connect server has its own distinct set of tokens. See the [`op connect token` command reference](/docs/cli/reference/management-commands/connect#connect-token). :::tip Export your Connect server access token as an environment variable. Doing so might prove useful if you decide to configure another tool like the [Kubernetes Injector](/docs/k8s/injector/), [Kubernetes Operator](/docs/k8s/operator/), or other integrations. However, keep in mind that the recommended way to use the Connect server token with Kubernetes is as a Kubernetes Secret. ```shell export OP_CONNECT_TOKEN=<token> ``` ::: ### Step 2: Deploy a 1Password Connect Server **Docker:** To deploy a Connect server using a Docker Compose file, you'll need to start two Docker images: - [1password/connect-api ](https://hub.docker.com/r/1password/connect-api) serves the Connect server REST API. - [1password/connect-sync ](https://hub.docker.com/r/1password/connect-sync) keeps the information available on the Connect server in sync with 1Password.com. :::info If you aren't familiar with Docker or Docker Compose, refer to the [Docker Compose documentation ](https://docs.docker.com/compose/) for more information. ::: 1. Make sure you have [Docker ](https://docs.docker.com/engine/install/) and [Docker Compose ](https://docs.docker.com/compose/install/) on your machine. 2. Create a Docker Compose file to deploy the 1Password Connect Server containers in the directory where you saved your `1password-credentials.json` file. You can also use the example [`docker-compose.yaml` file](https://i.1password.com/media/1password-connect/docker-compose.yaml). If the credentials file is in the other directory, update the `volumes` section to point to the correct credentials file location. :::tip You can set any of the [Connect server environment variables](/docs/connect/server-configuration/) in the `docker-compose.yaml` file by adding an environment attribute to each container. Doing so lets you specify things like the `1password-credentials.json` file location, the log level, and the HTTP port. Refer to the [Docker environment attribute documentation ](https://docs.docker.com/compose/environment-variables/set-environment-variables/) for more information. ::: 3. Make sure Docker is running. You can [check if the Docker daemon is running ](https://docs.docker.com/config/daemon/troubleshoot#check-whether-docker-is-running) with the `docker info` command in a terminal application. 4. Start the Docker containers with Docker Compose. Run the following command in the directory with the `docker-compose.yaml` file. ```shell docker compose up ``` :::tip You can run the containers in the background using the `-detach` flag or the `-d` flag. Refer to the [`docker compose up` reference ](https://docs.docker.com/engine/reference/commandline/compose_up/) for more information. ::: By default, you can access the Connect REST API through port `8080` on the local host. Refer to the [1Password Connect server API reference](/docs/connect/api-reference/) for more information. #### Test the Connect server REST API You can make sure the [Connect server REST API](/docs/connect/api-reference/) is accessible using a [`curl` ](https://curl.se/docs/manpage.html) command, one of the 1Password Connect server API endpoints, and the token you created. 1. Export the Connect server access token as an environment variable. This is the same token you created in [Step 1](#step-1). Alternatively, you can replace `$OP_API_TOKEN` with the token string in the `curl` request. :::tip If you forgot your token, you can create another one with the [`op connect token create` command](/docs/cli/reference/management-commands/connect#connect-token-create). ::: ```shell export OP_API_TOKEN="<token>" ``` 2. Use the following example [`curl` ](https://curl.se/docs/manpage.html) command to list the vaults connected to the Connect server. ```shell curl \ -H "Accept: application/json" \ -H "Authorization: Bearer $OP_API_TOKEN" \ http://localhost:8080/v1/vaults ``` To stop the Docker containers, run `docker compose down`. **Kubernetes:** You can deploy a Connect server with Kubernetes. The easiest way to do this is with the [1Password Connect and Operator Helm chart](/docs/k8s/helm/). :::warning[caution] Before you start, you must have a Kubernetes cluster deployed. If you don't already have a cluster, you can create one locally using [minikube ](https://minikube.sigs.k8s.io/docs/start/) or use the [Play with Kubernetes ](https://labs.play-with-k8s.com/) playground. ::: 1. Make sure you have [Docker ](https://docs.docker.com/engine/install/) installed and running on your machine. 2. Install the latest [Helm ](https://helm.sh) release. 3. Add the 1Password Helm chart repository. The following command adds the [1Password Helm chart repository](/docs/k8s/helm/) to your local instance of Helm. This allows you to download and install all the charts from 1Password's GitHub repository. ```shell helm repo add 1password https://1password.github.io/connect-helm-charts/ ``` 4. Install the 1Password Connect server using Helm. The following command deploys the 1Password Connect server using the `1password-credentials.json` file. :::tip You can find the `1password-credentials.json` file in the directory where you created the Connect server. ::: ```shell helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json ``` #### Other ways to deploy Here are some ways you can deploy a Connect server on a Kubernetes cluster: ##### Deploy without Helm You can deploy a Connect server on a Kubernetes cluster without using Helm charts. See the [sample Kubernetes deployment ](https://github.com/1Password/connect/tree/main/examples/kubernetes) on 1Password's GitHub that uses [cert-manager](https://cert-manager.io/) to provision a TLS (transport layer security) certificate for an external domain. ##### Deploy alongside the Kubernetes Operator {#with-operator} The 1Password Connect Kubernetes Operator integrates [Kubernetes Secrets ](https://kubernetes.io/docs/concepts/configuration/secret/) with 1Password. It also auto-restarts deployments when 1Password items are updated. [Learn more about the Kubernetes Operator](/docs/k8s/operator/). ### Step 3: Set up applications and services to get information from 1Password Applications and services get information from 1Password through REST API requests to a Connect server. The requests are authenticated with an access token. [Create a new token](/docs/connect/manage-connect#create-a-token) for each application or service you use. #### Languages [_[]_ Go](https://github.com/1Password/connect-sdk-go) [_[]_ Node.js](https://github.com/1Password/connect-sdk-js) [_[]_ Python](https://github.com/1Password/connect-sdk-python) #### Plugins [_[]_ Terraform provider](https://github.com/1Password/terraform-provider-onepassword) [_[]_ Kubernetes integrations](/docs/k8s/integrations/) [_[]_ Hashicorp Vault backend](https://github.com/1Password/vault-plugin-secrets-onepassword) [_[]_ Ansible collection](/docs/connect/ansible-collection/) If your language or platform isn't listed, you can [build your own client using the 1Password Connect Server REST API](/docs/connect/api-reference/). You can also [use 1Password CLI](/docs/connect/cli/) with your Connect server to provision secrets and retrieve item information on the command line. ## Get help To change the vaults a token has access to, [issue a new token](/docs/connect/manage-connect#create-a-token). To get help and share feedback, join the discussion with the [1Password Support Community](https://1password.community/categories/secrets-automation/). --- ## Manage Connect servers :::info As of Feb 27, 2025, all 1Password customers have unlimited access to Connect. ::: A Connect server is a type of [Secrets Automation workflow](/docs/secrets-automation/) that allows you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure using a private REST API provided by 1Password Connect Server. You can use 1Password.com or the [Connect REST API](/docs/connect/api-reference/) to: Control which team members and applications have access to which Connect server access tokens. Monitor and audit access and item usage. Secure applications by choosing when Connect server access tokens expire. Create and revoke Connect server access tokens. _[]_ ## Manage permissions {#manage-access} With 1Password Business or 1Password Teams, you can manage Connect server permissions with [groups](#global-permissions), or more granularly, with [environments](#environment-permissions). This allows for enforcement of security best practices. [Learn more about Connect security.](/docs/connect/security/) :::tip You can also manage group access using [automated provisioning](https://support.1password.com/scim/). ::: ### Manage global permissions {#global-permissions} Groups allow you to specify one or more users who can access Connect servers. To assign groups (such as Owners and Administrators) to manage Connect servers: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select [**Permissions**](https://start.1password.com/developer-tools/permissions) at the top of the page, then select [**Secrets Automation**](https://start.1password.com/developer-tools/permissions/C). 4. In the Managers section, select **Manage**, then choose the groups you want to manage Connect servers. 5. Select **Update Groups**. _[Manage Secrets Automation managers]_ ### Manage environment permissions {#environment-permissions} Environments allow you to override global permissions (with groups) for a specific Connect server environment. To assign groups (such as Owners and Administrators) to manage a specific Connect server: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/) in the sidebar. 3. Select [**Permissions**](https://start.1password.com/developer-tools/permissions) at the top of the page, then select [**Secrets Automation**](https://start.1password.com/developer-tools/permissions/C). 4. In the Environments section, select **Manage**. 5. In the Permissions section, select **Manage**, then choose the groups you want to manage Connect servers in the environment. 6. Select **Update Groups**. ## Manage access tokens You can use [Connect server access tokens](/docs/connect/concepts#connect-server-access-token) to authenticate with your Connect server in your applications and services. - [Create an access token.](#create-a-token) - [Set an access token expiration.](#set-a-token-expiration) - [Revoke an access token.](#revoke-a-token) - [Rename an access token.](#rename-a-token) ### Create a token To create a Connect server access token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to create an access token. 4. Select **New Token**. 5. Follow the onscreen instructions to issue the token. :::warning[caution] You can't edit the vaults a token can access after you create it. If you want to change the vaults a token can access, you must revoke the token and create a new one. ::: Connect server access tokens support up to 100 vaults each. If you grant a Connect token access to more than 100 vaults, the server may reject requests. ### Set a token expiration When you create a Connect server access token, you can set the token's expiration time to 30, 90, or 180 days. When the expiration time elapses, 1Password revokes the token. To create a token with an expiration date: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to create an access token. 4. Select **New Token**. 5. Set the "Expires After" to **30 days**, **90 days**, or **180 days**. 6. Follow the onscreen instructions. ### Revoke a token To revoke a Connect server access token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to manage access tokens. 4. Select next to the token you want to revoke, then select **Revoke**. ### Rename a token To rename a Connect server access token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active/) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to manage access tokens. 4. Select next to the token you want to rename, then select **Rename** and enter a new name. ## Grant or revoke access to vaults {#vault-access} To grant or revoke access to vaults: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to grant or revoke access to vaults. 4. In the Vaults section, select **Manage** and choose the vaults you want to add or remove. 5. Select **Update Vaults**. You can't grant Connect servers access to your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault, or your default [Shared](https://support.1password.com/1password-glossary#shared-vault) vault. _[Manage which vaults have access to each token]_ ## Monitor item usage Connect servers send [reports about item usage](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault) to the 1Password server every time an item is accessed so you can monitor item usage. :::info Item usage information might take a few hours to sync with 1Password.com. ::: To view item usage for a Connect server: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment (Connect server) you want to monitor. 4. Under Version, select **More Actions** > **View Item Usage Report**. For more information, visit [Create reports in 1Password Business](https://support.1password.com/reports/). ### About Connect server item usage Items accessed through a Connect server update specific fields in the following manner: - The **Action** field in the report always shows Display. - The **Used by** field always includes the name of the Connect server (not the Connect server access token). Connect servers only report item usage when they have a working connection to the 1Password server. If a Connect server can't reach the 1Password server (for example, when it updates or restarts), it might lose item usage information from that time period. Item usage reporting continues when the Connect server has a working connection to the 1Password server again. --- ## 1Password Connect 1Password Connect Servers allow you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure using a private REST API. Because Connect servers cache your data in your infrastructure, they allow unlimited re-requests after the server fetches your secrets. The only request quotas that apply to Connect servers are the internal rate limits 1Password employs to keep our services stable and available. These only apply when a Connect server fetches secrets for the first time, like when the Connect server starts. You can integrate a Connect server into your infrastructure and communicate with it over HTTP using one of the Connect SDK libraries (such as [Go](https://github.com/1Password/connect-sdk-go), [Python](https://github.com/1Password/connect-sdk-python), or [JavaScript](https://github.com/1Password/connect-sdk-js)) or using a custom integration. :::tip Not sure if Connect servers are for you? See the [Secrets Automation comparison table](/docs/secrets-automation#comparison). ::: _[The Connect server is part of your environment, and communicates to Your Apps using access tokens and a REST API.]_ ## Use cases You can use 1Password Connect to accomplish a variety of tasks: - **Reduce latency and downtime**: Deploy a Connect server in your infrastructure, giving you complete control. Self-hosting also reduces latency and has security benefits, as only your services can interact with Connect. You can also deploy redundant Connect servers to further increase availability. - **Provision web services with secrets**: Use a Connect server to provision an account with a secret stored in 1Password. If a web service needs access to a database (and the credentials for the database are in 1Password), you can use a Connect server to provision an account with the needed secret and allow the web service to access the secret during test runs. - **Automate secrets management**: Use a Connect server to automate scripts to manage secrets. Using a Connect server helps you implement the principle of least privilege and avoid the limitations of personal accounts (for example, SSO and MFA requirements). - **Load secrets into CI/CD pipelines**: Use a Connect server to automatically access your secrets in continuous integration environments. You can use a Connect server to use 1Password items in your CI/CD pipeline for testing and deploying code. Doing so maintains security and avoids using sensitive information with a personal account. - **Secure infrastructure secrets**: Use a Connect server to make sure infrastructure secrets aren't tied to a personal user account. - **Streamline development workflows**: Use a Connect server to securely share and manage infrastructure secrets to streamline development workflows. - **Secure Kubernetes environments**: Use a Connect server to access and sync 1Password secrets in a Kubernetes environment. ## Get started Learn how to get started and how to create, manage, and integrate with Connect servers. Get started --- ## About 1Password Connect Server security You can deploy one or more 1Password Connect servers in your infrastructure to act as a bridge between your applications and the 1Password service. Connect servers allow you to securely share information from 1Password with your applications, tools, and pipelines through the [Connect REST API](/docs/connect/api-reference/). Review the sections on the page to learn more about Connect server security. For information about 1Password security practices, visit the [1Password Security homepage](https://1password.com/security). ## Access control When you [create a Connect server](/docs/connect/get-started/), you select the vaults it can access. Connect servers can only access the vaults you explicitly allow them to access through a [Connect server access token](#connect-server-access-tokens). ### Authorization Only authorized clients can get information from a Connect server. When a client application, service, or API requests information from a Connect server, the HTTP request must have an `Authorization` header containing an authorization token. Otherwise, the Connect server rejects the request. Authorization tokens are only valid for the Connect server they're created for. They're signed by the key for the 1Password account the Connect server uses, using the [ES256 signing algorithm ](https://datatracker.ietf.org/doc/html/rfc7518). ### Usage reports [Usage reports](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault) can be created for users or vaults. Usage reports for team members include information on the number of vaults, groups, and items a team member can access, an overview of vaults where a team member has accessed items, when those items were last accessed, and the action performed. Usage reports for vaults include a list of items showing when they were last accessed, the action performed, and the team member who performed the action. These reports can be helpful when offboarding team members. ## Connect server access tokens A Connect server access token is an authentication string that allows the Connect server to authenticate with 1Password. Each Connect server can have one or more Connect server access tokens, which allows for more fine tuned [access control](#access-control). Connect server tokens can only access information in the vaults you granted them access to. This allows you more granular control over the vaults a Connect server deployment can access. For example, you can grant a Connect server token access to a specific subset of the vaults the Connect server has access to. ### Token rotation You can't change or update Connect server access tokens. If a Connect server token becomes compromised, you must create a new token. To rotate a Connect server access token: 1. [Create a new Connect server access token.](/docs/connect/manage-connect#create-a-token) 2. Update all references to the old Connect token. 3. [Revoke access to the old Connect token.](/docs/connect/manage-connect#revoke-a-token) ## Security model The Connect server security model has the following guarantees: - A Connect server access token can only read items from vaults you've explicitly given it `READ` access to. - A Connect server access token can only update, delete, and create items for vaults it has you've given it `WRITE` access to. - You can only give a Connect token access to vaults that you have access to. - A Connect server access token associated with a deleted account can't authenticate. - You can't use a Connect server access token to create another Connect server access token. ## Credentials file Creating a Connect server generates a credentials file named `1password-credentials.json`. This file has the following components: | Component | Description | | ---------------- | ------------------------------------------------------------ | | `verifier` | Connect servers use the `verifier` as part of an additional authentication of the bearer token. | | `encCredentials` | The `encCredentials` contains the encrypted credentials necessary for the associated service account. | | `uniqueKey` | The `uniqueKey` identifies the Connect server between its two running processes: the client-facing service and the synchronization service. | | `version` | The `version` indicates the Connect server version number. | | `deviceUuid` | The `deviceUuid` contains the UUID of the device. | ## Responsible disclosure 1Password requests you practice responsible disclosure if you discover a vulnerability. If you find a vulnerability in 1Password, [submit a report on HackerOne. ](https://hackerone.com/1password) --- ## Configure your Connect server This article documents Connect server [environment variables](#environment-variables) and special configuration options, such as [TLS](#tls) and [manual bus configuration](#manual-bus-configuration). 1Password Connect Server consists of two containers running in the same network: - The Connect API container ([`1password/connect-api` ](https://hub.docker.com/r/1password/connect-api)) - The Connect sync container ([`1password/connect-sync` ](https://hub.docker.com/r/1password/connect-sync)) Both containers require a shared volume to store an encrypted copy of your data. ## Requirements Before you can configure your 1Password Connect Server, you must: - [Sign up for 1Password](https://1password.com/pricing/password-manager). - [Setup a Connect server](/docs/connect/get-started/). ## Environment variables The following table lists the available environment variables, their description, and the containers that support them. Most of the environment variables apply to the Connect API and Connect sync containers, but some only apply to the Connect API container. | **Environment variable** | **Description** | **Container support** | | ------------------------ | ------------------------------------------------------------ | ------------------------------------------- | | `OP_SESSION` | The path to the `1password-credentials.json` file. You can also set the value to the [Base64-encoded content of the `1password-credentials.json` file](/docs/connect/aws-ecs-fargate#get-started). **Acceptable values**: A full file path to the `1password-credentials.json` file. **Default value**: `~/.op/1password-credentials.json` | • Connect API• Connect sync | | `OP_HTTP_PORT` | The port for the HTTP server. **Acceptable values**: Any available port number. **Default value**: `8080` | • Connect API• Connect sync | | `OP_LOG_LEVEL` | The logging level of the container. **Acceptable values**: `info`, `error`, `debug`**Default value**: `info` | • Connect API• Connect sync | | `XDG_DATA_HOME` | The path in which to create the `.op/data/` directory. See [Data volume](#data-volume). **Acceptable values**: A valid file path. **Default value**: `/home/opuser/.op/data` | • Connect API• Connect sync | | `OP_BUS_PORT` | The port for listening to incoming bus connections from other containers. See [Manual bus configuration](#manual-bus-configuration) for more details.**Acceptable values**: Any available port number. **Default value**: A random free port | • Connect API• Connect sync | | `OP_BUS_PEERS` | A comma-separated list of `[hostname]:[bus port]` pairs of other containers to connect to. See [Manual bus configuration](#manual-bus-configuration) for more details.**Acceptable values**: A comma-separated list of `[hostname]:[bus port]` pairs. **Default value**: No default because this variable is optional. | • Connect API• Connect sync | | `OP_HTTPS_PORT` | The port for the HTTP server when using [TLS](#tls). **Acceptable values**: Any available port number.**Default value**: `8443` | • Connect API | | `OP_SYNC_TIMEOUT` | The time (in seconds) to wait for the initial sync to complete. **Acceptable values**: A time duration (for example, `1h`, `30m`, `20s`).**Default value**: `10s` (10 seconds) | • Connect API | | `OP_TLS_KEY_FILE` | The path to the private key file. Only use this environment variable if you plan to [use TLS with your own certificate](#tls-custom).**Acceptable values**: A valid file path.**Default value**: No default because this variable is optional. | • Connect API | | `OP_TLS_CERT_FILE` | The path to the certificate file. This should be the full certificate chain. Only use this environment variable if you plan to [use TLS with your own certificate](#tls-custom).**Acceptable values**: A valid file path.**Default value**: No default because this variable is optional. | • Connect API | | `OP_TLS_USE_LETSENCRYPT` | Only use this environment variable if you want to [use TLS with a Lets Encrypt certificate](#tls-lets-encrypt).**Acceptable values**: Any value (for example, `1`, `true`, or `yes`).**Default value**: No default because this variable is optional. | • Connect API | | `OP_TLS_DOMAIN` | The (sub-)domain for which to request a certificate. The DNS records for this domain must point to the Connect server. See [TLS](#tls).**Acceptable values**: Any domain (or subdomain) name.**Default value**: No default because this variable is optional. | • Connect API | ### Data volume The default location of the shared volume is `/home/opuser/.op/data`. If you set the `XDG_DATA_HOME` environment variable to a path other than `/home/opuser/`, make sure you mount your data volume at the same path. ### TLS By default, 1Password Connect Server is configured for use within a trusted network. If you plan to use Connect outside a trusted network, consider configuring [Transport Layer Security (TLS) ](https://www.cloudflare.com/learning/ssl/transport-layer-security-tls/). You can configure TLS for the connection between your application and Connect by [providing your own certificate](#tls-custom) or letting Connect request a certificate [using Let's Encrypt](#tls-lets-encrypt). Connect listens on the port defined by the `OP_HTTPS_PORT` environment variable (default `8443`) when you use TLS. #### Use your own certificate {#tls-custom} Connect can use a PEM-encoded private key and certificate by setting the following two environment variables for the Connect API container: 1. Set `OP_TLS_KEY_FILE` to the path to the private key file. 2. Set `OP_TLS_CERT_FILE` to the path to the certificate file. This should be the full certificate chain. #### Use Let's Encrypt {#tls-lets-encrypt} Connect can also request a certificate from the [Let's Encrypt ](https://letsencrypt.org/) Certificate Authority (CA). For this, you must set two environment variables for the Connect API container: 1. Set `OP_TLS_USE_LETSENCRYPT` to any value. 2. Set `OP_TLS_DOMAIN` to the (sub-)domain for which to request a certificate. The DNS records for this domain must point to the Connect server. As long as Connect is running, its HTTPS listener must be reachable on a public IP at port `443` (either by setting `OP_HTTPS_PORT=443` or by forwarding traffic at port `443` to the Connect server's `OP_HTTPS_PORT` value). This makes sure the Connect server can refresh its Let's Encrypt certificate. ### Manual bus configuration :::warning[caution] Manual bus configuration only works with Connect server [version 1.5.0 ](https://github.com/1Password/connect/blob/main/CHANGELOG.md#v150) and later. ::: By default, the two containers (Connect API and Connect sync) automatically discover and connect to the shared bus. This discovery mechanism requires the `NET_BROADCAST` capability, which you can't always grant to containers. However, it’s possible to manually configure the shared bus. To manually configure the shared bus: 1. Assign a static port for the bus by setting the `OP_BUS_PORT` environment variable to a free port for both containers. 2. Set the `OP_BUS_PEERS` environment variable for the Connect API container to `[hostname]:[bus port]`, where `hostname` is the name of the Connect sync container and `bus port` the value of `OP_BUS_PORT` for the Connect sync container. 3. Set the `OP_BUS_PEERS` environment variable for the Connect sync container to `[hostname]:[bus port]`, where `hostname` is the name of the application container and `bus port` is the value of `OP_BUS_PORT` for the Connect API container. The following examples show the configuration values necessary for the Connect API container and the Connect sync container. **Connect API container:** The following example sets environment variables for a Connect API container called op-connect-api. ```txt [{ "color": "bitsblue", "lineNo": 2, "substr": "op-connect-api" }] OP_BUS_PORT=11223 OP_BUS_PEERS=op-connect-api:11223 ``` **Connect sync container:** The following example sets environment variables for a Connect sync container called op-connect-sync. ```txt [{ "color": "lagoon", "lineNo": 2, "substr": "op-connect-sync" }] OP_BUS_PORT=11223 OP_BUS_PEERS=op-connect-sync:11223 ``` ## Examples The [1Password Connect repository ](https://github.com/1Password/connect) has example Connect server configurations using Kubernetes, Docker Compose, and AWS Fargate. - [Example Kubernetes deployment ](https://github.com/1Password/connect/tree/main/examples/kubernetes) - [Example Docker Compose deployment ](https://github.com/1Password/connect/tree/main/examples/docker/compose) - [Example AWS Fargate deployment ](https://github.com/1Password/connect/tree/main/examples/aws-ecs-fargate) --- ## Load secrets from 1Password into CircleCI With the [1Password Secrets orb for CircleCI ](https://circleci.com/developer/orbs/orb/onepassword/secrets), you can securely load secrets from 1Password into CircleCI CI/CD pipelines using [secret references](/docs/cli/secret-reference-syntax). Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. [CircleCI orbs ](https://circleci.com/docs/orb-intro/) are packages containing YAML configuration files. Using an orb allows you to refer to these configurations with a single line of code. :::info The [1Password Secrets orb for CircleCI ](https://github.com/1password/secrets-orb) is officially supported and maintained by 1Password, but community contributions are welcome. ::: You can use the orb with a [1Password Connect Server](/docs/connect/) or a [1Password Service Account](/docs/service-accounts/). See the video below for a brief introduction to using 1Password Service Accounts with CircleCI and Docker. ## Requirements The requirements for getting started with the 1Password for CircleCI orb vary depending on whether you use a service account or Connect server. **Service account:** Before you use 1Password for CircleCI with a service account, you need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create a service account.](/docs/service-accounts/) - Create a [CircleCI ](https://circleci.com/) account. **Connect:** Before you use 1Password for CircleCI with a Connect server, you need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create and deploy a Connect server.](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) - Create a [CircleCI ](https://circleci.com/) account. :::warning[caution] Connect credentials take precedence over service account credentials. If you've set the `OP_CONNECT_HOST` or `OP_CONNECT_TOKEN` environment variables alongside `OP_SERVICE_ACCOUNT_TOKEN`, the Connect credentials take precedence over the provided service account token. You must unset the Connect environment variables to make sure the action uses the service account token. ::: ## Get started **Service account:** 1. Set the service account token environment variable in CircleCI. On the [CircleCI settings page ](https://circleci.com/docs/introduction-to-the-circleci-web-app#project-settings), set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to token of the service account to use to load secrets. 2. Edit the CircleCI configuration file and make the following updates: - Update the [CircleCI `config.yml` file ](https://circleci.com/docs/config-intro/) to use the 1Password for CircleCI orb. - Specify the version number or use `volatile` to use the latest version number. Add the onepassword/secrets orb to your `config.yml` file. ```yaml [{ "color": "tangerine", "lineNo": 2, "substr": "onepassword/secrets" }] title="config.yml" orbs: 1password: onepassword/secrets@1.0.0 ``` To use the *latest* version of 1Password Secrets orb in your project, set `volatile` as the version number. ```yaml [{ "color": "lagoon", "lineNo": 2, "substr": "volatile" }] title="config.yml" orbs: 1password: onepassword/secrets@volatile ``` 3. Install 1Password CLI version **2.18.0 or later** as the first step of a CircleCI job using the 1password/install-cli [command](#commands). You must install the CLI in the pipeline for the 1Password CircleCI orb to function. Earlier versions of 1Password CLI don't support service accounts. Find the latest version number in the [1Password CLI release notes](https://releases.1password.com/developers/cli/). ```yaml title="config.yml" {3} [{ "lineNo": 3, "substr": "2.x.x", "editableId": "version-number", "label": "Version number" }] steps: - 1password/install-cli: version: 2.x.x ``` 4. Use 1Password CLI commands in subsequent steps in the pipeline. See the following example `config.yml` files. Make sure to update `2.x.x` to [1Password CLI version 2.18.0 or later](https://releases.1password.com/developers/cli/). **Example 1:** ```yaml title="config.yml" {10} [{ "color": "dahlia", "lineNo": 9, "substr": "1password/install-cli" }, { "lineNo": 10, "substr": "2.x.x", "editableId": "version-number", "label": "Version number" }] version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - 1password/install-cli: version: 2.x.x - checkout - run: shell: op run -- /bin/bash environment: AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key command: | echo "This value will be masked: $AWS_ACCESS_KEY_ID" echo "This value will be masked: $AWS_SECRET_ACCESS_KEY" ./deploy-my-app.sh workflows: deploy: jobs: - deploy ``` **Example 2:** ```yaml title="config.yml" {12} [{ "color": "dahlia", "lineNo": 11, "substr": "1password/install-cli" }, { "lineNo": 12, "substr": "2.x.x", "editableId": "version-number", "label": "Version number" }] description: Install 1Password CLI within a job and make it useable for all the commands following the installation. usage: version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - 1password/install-cli: version: 2.x.x - checkout - run: | docker login -u $(op read op://company/docker/username) -p $(op read op://company/docker/password) docker build -t company/app:${CIRCLE_SHA1:0:7} . docker push company/app:${CIRCLE_SHA1:0:7} workflows: deploy: jobs: - deploy ``` **Connect:** 1. Set the Connect server environment variables in CircleCI. On the [CircleCI settings page ](https://circleci.com/docs/introduction-to-the-circleci-web-app#project-settings), set the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables for the Connect server to use to load secrets: - Set `OP_CONNECT_TOKEN` to the Connect server token. - Set `OP_CONNECT_HOST` to the Connect server hostname or IP address. 2. Edit the CircleCI configuration file. Update the [CircleCI `config.yml` file ](https://circleci.com/docs/config-intro/) to use the 1Password for CircleCI orb. Make sure to specify the version number or use `volatile` to use the latest version number. Add the onepassword/secrets orb to your `config.yml` file. ```yaml [{ "color": "tangerine", "lineNo": 2, "substr": "onepassword/secrets" }] title="config.yml" orbs: 1password: onepassword/secrets@1.0.0 ``` To use the *latest* version of 1Password Secrets orb in your project, set `volatile` as the version number. ```yaml [{ "color": "lagoon", "lineNo": 2, "substr": "volatile" }] title="config.yml" orbs: 1password: onepassword/secrets@volatile ``` 3. Install 1Password CLI. You must install [1Password CLI](/docs/cli/) in the pipeline for the 1Password CircleCI orb to function: - Install the CLI as the first step of a CircleCI job using the 1password/install-cli [command](#commands). - Use 1Password CLI commands in subsequent steps in the pipeline. See the following example `config.yml` files. **Example 1:** ```yaml title="config.yml" version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - 1password/install-cli - checkout - run: shell: op run -- /bin/bash environment: AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key command: | echo "This value will be masked: $AWS_ACCESS_KEY_ID" echo "This value will be masked: $AWS_SECRET_ACCESS_KEY" ./deploy-my-app.sh workflows: deploy: jobs: - deploy ``` **Example 2:** ```yaml title="config.yml" [{ "color": "dahlia", "lineNo": 11, "substr": "1password/install-cli" }] description: Install 1Password CLI within a job and make it useable for all the commands following the installation. usage: version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - 1password/install-cli - checkout - run: | docker login -u $(op read op://company/docker/username) -p $(op read op://company/docker/password) docker build -t company/app:${CIRCLE_SHA1:0:7} . docker push company/app:${CIRCLE_SHA1:0:7} workflows: deploy: jobs: - deploy ``` ## Reference The following sections document the 1Password for CircleCI orb [commands](#commands) and the [secret reference syntax](#secret-reference-syntax). ### Commands There are three commands to use when you configure your orb: `1password/install-cli`, `1password/exec`, and `1password/export`. :::warning[caution] Only some commands mask secrets. Both the `1password/exec` orb command and the [`op run`](/docs/cli/reference/commands/run/) shell wrapper automatically mask secrets from the CircleCI log output. If secrets accidentally get logged, 1Password replaces them with `<concealed by 1Password>`. The `1password/export` command doesn't mask secrets. ::: | Command | Description | Masks secrets | | ------- | -------- | ------- | | 1password/install-cli | Installs 1Password CLI. You must use this command as a step to use 1Password CLI commands in subsequent steps. | N/A | | 1password/exec | Loads secrets on demand and executes the commands requiring secrets. See [loading secrets with the `exec` command](#load-exec). | Yes | | 1password/export | Loads secrets with references exported in the environment and makes them available to subsequent steps of the job. See [loading secrets with the `export` command](#load-export). | No | ### Secret reference syntax You can make secrets available to CircleCI jobs and steps by including references to them in the environment using secret references. Secret reference URIs point to where a secret is saved in your 1Password account using the names (or [unique identifiers](/docs/cli/reference#unique-identifiers-ids)) of the vault, item, section, and field where the information is stored. ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "vault-name" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "item-name" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "section-name" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "field-name" }] op://vault-name/item-name/[section-name/]field-name ``` Visit the [secret reference syntax](/docs/cli/secret-reference-syntax/) documentation to access examples and learn more about referencing secrets. ## Usage examples Explore the following sections to learn about specific use case examples for the 1Password CircleCI orb. - [Load secrets with `exec`](#load-exec) - [Load secrets with `export`](#load-export) ### Load secrets with the `exec` command {#load-exec} To load secrets with the `1password/exec` command: 1. Install 1Password CLI with 1password/install-cli. If you're using a service account, make sure to set the [1Password CLI version](https://releases.1password.com/developers/cli/) to `2.18.0` or later. 2. Use the 1password/exec command to load secrets on demand and execute commands that require secrets. After you add the 1password/exec command as a step in your job, subsequent steps of the job can access secrets. The following example shows how to use the 1password/exec command to resolve variables at the job level. The `exec` command automatically masks any secrets or sensitive values that might be accidentally logged. ```yaml [{ "color": "tangerine", "lineNo": 16, "substr": "1password/exec" }, { "color": "dahlia", "lineNo": 14, "substr": "1password/install-cli" }, { "lineNo": 15, "substr": "2.x.x", "editableId": "version-number", "label": "Version number" }] title="config.yml" version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current environment: AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key steps: - checkout - 1password/install-cli: version: 2.x.x - 1password/exec: command: | echo "This value will be masked: $AWS_ACCESS_KEY_ID" echo "This value will be masked: $AWS_SECRET_ACCESS_KEY" ./deploy-my-app.sh workflows: deploy: jobs: - deploy ``` ### Load secrets with the `export` command {#load-export} To load secrets with the `1password/export` command: 1. Install 1Password CLI with 1password/install-cli. If you're using a service account, make sure to set the [1Password CLI version](https://releases.1password.com/developers/cli/) to `2.18.0` or later. 2. Use the 1password/export command to load the [secret references](#secret-reference-syntax) exported in the environment. 3. Access secrets in subsequent steps of the job. The following example shows how to use the 1password/export command to resolve variables at the job level. ```yaml title="config.yml" url="https://github.com/1Password/secrets-orb/blob/main/src/examples/export.yml" [{ "color": "sunbeam", "lineNo": 13, "substr": "1password/export" }, { "color": "dahlia", "lineNo": 11, "substr": "1password/install-cli" }, { "lineNo": 12, "substr": "2.x.x", "editableId": "version-number", "label": "Version number" }] version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - checkout - 1password/install-cli version: 2.x.x - 1password/export: var-name: AWS_ACCESS_KEY_ID secret-reference: op://company/app/aws/access_key_id - 1password/export: var-name: AWS_SECRET_ACCESS_KEY secret-reference: op://company/app/aws/secret_access_key - run: command: | echo "This value will not be masked: $AWS_ACCESS_KEY_ID" echo "This value will not be masked: $AWS_SECRET_ACCESS_KEY" ./deploy-my-app.sh workflows: deploy: jobs: - deploy ``` --- ## Load secrets from 1Password into GitHub Actions With the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password), you can securely load secrets from 1Password into GitHub Actions using [secret references](/docs/cli/secret-reference-syntax). Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. You can authenticate `load-secrets-action` with a [1Password Connect Server](/docs/connect/) or a [1Password Service Account](/docs/service-accounts/). See the video below for a brief introduction to using the GitHub Action with a service account. :::info Similar to regular [GitHub repository secrets ](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions), 1Password automatically masks sensitive fields that appear in GitHub Actions logs. If one of these values accidentally gets printed, it's replaced with `***`. ::: ## Requirements You can configure the action to authenticate to 1Password with either a [service account](/docs/service-accounts/) or a [Connect server](/docs/connect/). **Service account:** Before using the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) with a service account, you must: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create a service account.](/docs/service-accounts/) - Have the service account token on hand. **Connect:** Before using the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) with a Connect server, you must: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create and deploy a Connect server](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) in your infrastructure. - Have the Connect server hostname and Connect server token on hand. :::warning[caution] The [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) only supports Mac and Linux [runners ](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners). It doesn't work with Windows runners. ::: ## Get started The steps to get started vary depending on whether you use a service account or a Connect server. **Service account:** 1. Add the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) to your workflow. See [Adding an action to your workflow ](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#adding-an-action-to-your-workflow). 2. Add the service account token to your workflow. Create a secret for your GitHub repository named OP_SERVICE_ACCOUNT_TOKEN and set it to the service account token value. Visit [Using secrets in GitHub Actions ](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) to learn how. 3. Configure your workflow. Use the `1password/load-secrets-action/configure` action to specify the token of the service account you plan to get secrets from. The following example uses the `configure` command to set the service-account-token to the OP_SERVICE_ACCOUNT_TOKEN secret. ```yaml title="config.yml" [{ "color": "tangerine", "lineNo": 3, "substr": "service-account-token" }, { "color": "bitsblue", "lineNo": 3, "substr": "OP_SERVICE_ACCOUNT_TOKEN"}] uses: 1password/load-secrets-action/configure@v2 with: service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} ``` :::tip Setting the service-account-token in the `configure` step makes the value available to all subsequent steps. You can limit step access to the service account token by only using the service account token in specific steps. To use the service account token in a specific step, set it in the `env` variables for that step. ```yaml title="config.yml" env: OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} ``` ::: 4. Load a secret. Use the `1password/load-secrets-action` action to set an environment variable to a [secret reference URI](#secret-reference-syntax) that points to where a secret is stored in your 1Password account. The following example sets the SECRET environment variable to the value of a field titled `secret` within an item titled `hello-world` saved in a vault titled `app-cicd`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 3, "substr": "SECRET" }] uses: 1password/load-secrets-action@v2 env: SECRET: op://app-cicd/hello-world/secret ``` The action makes the referenced secret available as the `SECRET` environment variable for the next steps. **Connect:** 1. Add the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) (`load-secrets-action`) to your workflow. See [Adding an action to your workflow ](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#adding-an-action-to-your-workflow). 2. Add the Connect server token to your workflow. Create a secret named OP_CONNECT_TOKEN in your repository and set it to the Connect server token value. Visit [Using secrets in GitHub Actions ](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) to learn how. 3. Configure your workflow. Use the `1password/load-secrets-action/configure` action to specify the Connect server environment variable. The following example uses the configure command to: - Set the connect-host to the Connect server hostname (OP_CONNECT_HOST). - Set the connect-token to the OP_CONNECT_TOKEN secret. ```yaml title="config.yml" [{ "color": "dahlia", "lineNo": 3, "substr": "connect-host" }, { "color": "sunbeam", "lineNo": 3, "substr": "OP_CONNECT_HOST" }, { "color": "tangerine", "lineNo": 4, "substr": "connect-token" }, { "color": "bitsblue", "lineNo": 4, "substr": "OP_CONNECT_TOKEN" }] uses: 1password/load-secrets-action/configure@v2 with: connect-host: OP_CONNECT_HOST connect-token: ${{ secrets.OP_CONNECT_TOKEN }} ``` :::tip Setting the connect-token in the configure step makes the value available to all subsequent steps. You can limit step access to the service account token by only using the service account token in specific steps. To use the service account token in a specific step, set it in the `env` variables for that step. ```yaml title="config.yml" env: OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} ``` ::: 4. Load a secret. Use the `1password/load-secrets-action` action to set an environment variable to a [secret reference URI](#secret-reference-syntax) that points to where a secret is stored in your 1Password account. The following example sets the SECRET environment variable to the value of a field titled `secret` within an item titled `hello-world` saved in a vault titled `app-cicd`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 3, "substr": "SECRET" }] uses: 1password/load-secrets-action@v2 env: SECRET: op://app-cicd/hello-world/secret ``` The action makes the referenced secret available as the `SECRET` environment variable for the next steps. ## Reference The following sections document the [action inputs](#action-inputs) and [secret reference syntax](#secret-reference-syntax) for the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password). ### Action inputs The following table contains the available `configure` action inputs. | Action input | Environment variable | Description | | ----------------------- | -------------------------- | --------------------------------------------------------- | | `connect-host` | `OP_CONNECT_HOST` | The Connect server, hostname, IP address, or instance URL. | | `connect-token` | `OP_CONNECT_TOKEN` | The Connect server token. | | `service-account-token` | `OP_SERVICE_ACCOUNT_TOKEN` | The service account token. | ### Secret reference syntax Secret reference URIs point to where a secret is saved in your 1Password account using the names (or [unique identifiers](/docs/cli/reference#unique-identifiers-ids)) of the vault, item, section, and field where the information is stored. ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "vault-name" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "item-name" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "section-name" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "field-name" }] op://vault-name/item-name/[section-name/]field-name ``` Set an environment variable to a secret reference in your workflow YAML file, and the action will make the referenced secret available as the environment variable for the next steps. #### Example The following example shows how to reference the `secret-access-key` field of the `aws` item in the `app-cicd` vault. ```yaml title="config.yml" {4} [{ "badge": "1", "color": "sunbeam", "lineNo": 4, "substr": "app-cicd" },{ "badge": "2", "color": "lagoon", "lineNo": 4, "substr": "aws" },{ "badge": "3", "color": "dahlia", "lineNo": 4, "substr": "secret-access-key" }] - name: Load secret uses: 1password/load-secrets-action@v2 env: SECRET: op://app-cicd/aws/secret-access-key ``` - **Vault:** app-cicd - **Item:** aws - **Field:** secret-access-key ## Usage examples You can load secrets using the action in two ways: 1. [Use secrets from the action's output](#use-secrets-from-the-actions-output) 2. [Export secrets as environment variables](#export-secrets-as-environment-variables) ### Use secrets from the action's output You can use the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) to access secrets as environment variables. **Service account:** The following examples show how to load a secret from a service account and print the output when a `push` event occurs. You need to set an ID for the step to access its outputs. See [`outputs.<output_id>` ](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#outputsoutput_id). **Simple example:** The following example shows how to use a service account to load (and print) a secret (as the SECRET env variable) from 1Password. When you print a secret, 1Password automatically replaces it with `***`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 15, "substr": "SECRET" }] on: push jobs: hello-world: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Load secret id: op-load-secret uses: 1password/load-secrets-action@v2 with: export-env: false env: OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} SECRET: op://app-cicd/hello-world/secret - name: Print masked secret run: 'echo "Secret: ${{ steps.op-load-secret.outputs.SECRET }}"' # Prints: Secret: *** ``` **Advanced example:** The following example shows how to use a service account to load the `username` and `token` fields from the `docker` secret in 1Password (as DOCKERHUB_USERNAME and DOCKERHUB_TOKEN), then use them to log into Docker Hub. ```yaml title="config.yml" [{ "badge": "1", "color": "sunbeam", "lineNo": 25, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 26, "substr": "DOCKERHUB_TOKEN"}, { "badge": "1", "color": "sunbeam", "lineNo": 31, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 32, "substr": "DOCKERHUB_TOKEN"}] on: push name: Deploy app jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Configure 1Password Service Account uses: 1password/load-secrets-action/configure@v2 with: # Persist the 1Password Service Account Authorization token # for next steps. # Keep in mind that every single step in the job is now # able to access the token. service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} - name: Load Docker credentials id: load-docker-credentials uses: 1password/load-secrets-action@v2 with: export-env: false env: DOCKERHUB_USERNAME: op://app-cicd/docker/username DOCKERHUB_TOKEN: op://app-cicd/docker/token - name: Login to Docker Hub uses: docker/login-action@v1 with: username: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_USERNAME }} password: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_TOKEN }} - name: Build and push Docker image uses: docker/build-push-action@v2 with: push: true tags: acme/app:latest ``` **Connect:** The following examples show how to load a secret from a Connect server and print the output when a `push` event occurs. **Simple example:** The following example shows how to use a Connect server to load (and print) a secret (as the SECRET env variable) from 1Password. When you print a secret, 1Password automatically replaces it with `***`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 16, "substr": "SECRET" }] on: push jobs: hello-world: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Load secret id: op-load-secret uses: 1password/load-secrets-action@v2 with: export-env: false env: OP_CONNECT_HOST: connect-host OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} SECRET: op://app-cicd/hello-world/secret - name: Print masked secret run: 'echo "Secret: ${{ steps.op-load-secret.outputs.SECRET }}"' # Prints: Secret: *** ``` **Advanced example:** The following example shows how to use a Connect server to load the `username` and `token` fields from the `docker` secret in 1Password (as DOCKERHUB_USERNAME and DOCKERHUB_TOKEN), then use them to log into Docker Hub. ```yaml title="config.yml" [{ "badge": "1", "color": "sunbeam", "lineNo": 24, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 25, "substr": "DOCKERHUB_TOKEN"}, { "badge": "1", "color": "sunbeam", "lineNo": 30, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 31, "substr": "DOCKERHUB_TOKEN"}] on: push name: Deploy app jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Configure 1Password Connect uses: 1password/load-secrets-action/configure@v2 with: # Persist the 1Password Connect URL for next steps. You can also persist # the Connect token using input `connect-token`, but keep in mind that # every single step in the job would then be able to access the token. connect-host: OP_CONNECT_HOST - name: Load Docker credentials id: load-docker-credentials uses: 1password/load-secrets-action@v2 with: export-env: false env: OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} DOCKERHUB_USERNAME: op://app-cicd/docker/username DOCKERHUB_TOKEN: op://app-cicd/docker/token - name: Login to Docker Hub uses: docker/login-action@v1 with: username: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_USERNAME }} password: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_TOKEN }} - name: Build and push Docker image uses: docker/build-push-action@v2 with: push: true tags: acme/app:latest ``` ### Export secrets as environment variables You can use the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) to use loaded secret outputted from the `steps.step-id.outputs.secret-name`. **Service account:** The following examples show how to use a service account to load a 1Password secret as an environment variable. **Simple example:** The following example shows how to use a service account to load a secret as an environment variable named SECRET. When you print a secret, 1Password automatically replaces it with `***`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 15, "substr": "SECRET" }, { "color": "lagoon", "lineNo": 18, "substr": "SECRET" }] on: push jobs: hello-world: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Load secret uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true env: OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} SECRET: op://app-cicd/hello-world/secret - name: Print masked secret run: 'echo "Secret: $SECRET"' # Prints: Secret: *** ``` **Advanced example:** The following example shows how to use a service account to load the `username` and `token` fields from the `docker` secret in 1Password as environment variables named DOCKERHUB_USERNAME and DOCKERHUB_TOKEN, then uses them to log into Docker Hub. It also loads the `access-key-id` and `secret-access-key` fields from the `aws` secret in 1Password as environment variables named AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, then uses them to deploy to AWS. ```yaml title="config.yml" [{ "badge": "1", "color": "sunbeam", "lineNo": 25, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 26, "substr": "DOCKERHUB_TOKEN"}, { "badge": "1", "color": "sunbeam", "lineNo": 31, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 32, "substr": "DOCKERHUB_TOKEN"}, { "badge": "3", "color": "lagoon", "lineNo": 51, "substr": "AWS_ACCESS_KEY_ID"}, { "badge": "4", "color": "bitsblue", "lineNo": 52, "substr": "AWS_SECRET_ACCESS_KEY"}, { "badge": "3", "color": "lagoon", "lineNo": 55, "substr": "AWS_ACCESS_KEY_ID"}, { "badge": "4", "color": "bitsblue", "lineNo": 55, "substr": "AWS_SECRET_ACCESS_KEY"}] on: push name: Deploy app jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Configure 1Password Service Account uses: 1password/load-secrets-action/configure@v2 with: # Persist the 1Password Service Account Authorization token # for next steps. # Keep in mind that every single step in the job is now able # to access the token. service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} - name: Load Docker credentials uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true env: DOCKERHUB_USERNAME: op://app-cicd/docker/username DOCKERHUB_TOKEN: op://app-cicd/docker/token - name: Login to Docker Hub uses: docker/login-action@v1 with: username: ${{ env.DOCKERHUB_USERNAME }} password: ${{ env.DOCKERHUB_TOKEN }} - name: Print environment variables with masked secrets run: printenv - name: Build and push Docker image uses: docker/build-push-action@v2 with: push: true tags: acme/app:latest - name: Load AWS credentials uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true # Remove local copies of the Docker credentials, which are not needed anymore unset-previous: true env: AWS_ACCESS_KEY_ID: op://app-cicd/aws/access-key-id AWS_SECRET_ACCESS_KEY: op://app-cicd/aws/secret-access-key - name: Deploy app # This script expects AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to be set, which was # done automatically by the step above run: ./deploy.sh ``` **Connect:** The folowing examples show how to use a Connect server to load a secret from 1Password as an environment variable. **Simple example:** The following example shows how to use a Connect server to load a secret as an environment variable named SECRET. When you print a secret, 1Password automatically replaces it with `***`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 16, "substr": "SECRET" }, { "color": "lagoon", "lineNo": 19, "substr": "SECRET" }] on: push jobs: hello-world: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Load secret uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true env: OP_CONNECT_HOST: connect-host OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} SECRET: op://app-cicd/hello-world/secret - name: Print masked secret run: 'echo "Secret: $SECRET"' # Prints: Secret: *** ``` **Advanced example:** The following example shows how to use a Connect server to load the `username` and `token` fields from the `docker` secret in 1Password as environment variables named DOCKERHUB_USERNAME and DOCKERHUB_TOKEN, then uses them to log into Docker Hub. It also loads the `access-key-id` and `secret-access-key` fields from the `aws` secret in 1Password as environment variables named AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, then uses them to deploy to AWS. ```yaml title="config.yml" [{ "badge": "1", "color": "sunbeam", "lineNo": 26, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 27, "substr": "DOCKERHUB_TOKEN"}, { "badge": "1", "color": "sunbeam", "lineNo": 32, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 33, "substr": "DOCKERHUB_TOKEN"}, { "badge": "3", "color": "lagoon", "lineNo": 53, "substr": "AWS_ACCESS_KEY_ID"}, { "badge": "4", "color": "bitsblue", "lineNo": 54, "substr": "AWS_SECRET_ACCESS_KEY"}, { "badge": "3", "color": "lagoon", "lineNo": 57, "substr": "AWS_ACCESS_KEY_ID"}, { "badge": "4", "color": "bitsblue", "lineNo": 57, "substr": "AWS_SECRET_ACCESS_KEY"}] on: push name: Deploy app jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Configure 1Password Connect uses: 1password/load-secrets-action/configure@v2 with: # Persist the 1Password Connect hostname for next steps. # You can also persist the Connect token using input # `connect-token`, but keep in mind that every single # step in the job would then be able to access the token. connect-host: OP_CONNECT_HOST - name: Load Docker credentials uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true env: OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} DOCKERHUB_USERNAME: op://app-cicd/docker/username DOCKERHUB_TOKEN: op://app-cicd/docker/token - name: Login to Docker Hub uses: docker/login-action@v1 with: username: ${{ env.DOCKERHUB_USERNAME }} password: ${{ env.DOCKERHUB_TOKEN }} - name: Print environment variables with masked secrets run: printenv - name: Build and push Docker image uses: docker/build-push-action@v2 with: push: true tags: acme/app:latest - name: Load AWS credentials uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true # Remove local copies of the Docker credentials, which are not needed anymore unset-previous: true env: OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} AWS_ACCESS_KEY_ID: op://app-cicd/aws/access-key-id AWS_SECRET_ACCESS_KEY: op://app-cicd/aws/secret-access-key - name: Deploy app # This script expects AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to be set, which was # done automatically by the step above run: ./deploy.sh ``` ## Troubleshooting If you try to create items using 1Password CLI in your GitHub pipelines (without using `load-secrets-action`), the command fails with the following error: ```text variant="bad" Failed to create item: invalid JSON ``` For example, the following results in an error: ```shell variant="bad" op item create --category=login --title='My Example Item' --vault='Test' \ --url https://www.acme.com/login \ --generate-password=20,letters,digits \ username=jane@acme.com \ 'Test Field 1=my test secret' \ 'Test Section 1.Test Field2[text]=Jane Doe' \ 'Test Section 1.Test Field3[date]=1995-02-23' \ 'Test Section 2.Test Field4[text]='$myNotes ``` The pipeline environment is in piped mode. This triggers the CLI's pipe detection, which expects a piped input. To create items in this environment, use a [JSON template](/docs/cli/item-template-json/) with your item details. 1. Get the template for the category of item you want to create: ```shell op item template get --out-file=new-item.json <category> ``` 2. Edit [the template](/docs/cli/item-template-json/) to add your information. 3. Pipe the item content to the command: ```shell cat new-item.json | op item create --vault <vault> ``` --- ## Load secrets from 1Password into Jenkins With the [1Password Secrets plugin for Jenkins ](https://plugins.jenkins.io/onepassword-secrets/), you can securely load secrets from 1Password as environment variables in a Jenkins CI/CD pipeline using [secret references](/docs/cli/secret-reference-syntax/). Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. You can authenticate the plugin with a [1Password Service Account](/docs/service-accounts/) or a [1Password Connect Server](/docs/connect/). :::info The 1Password Jenkins plugin is officially supported and maintained by 1Password. Community contributions are welcome. [View the repository on GitHub. ](https://github.com/jenkinsci/onepassword-secrets-plugin) ::: ## Requirements You can use the 1Password Secrets plugin for Jenkins with either a [service account](/docs/service-accounts/get-started/) or a [Connect server](/docs/connect/get-started/). If you configure both a service account and a Connect server, the Connect server takes precedence. **Service account:** - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create a service account.](/docs/service-accounts/get-started/) - [Have a Jenkins instance up and running. ](https://www.jenkins.io/doc/) **Connect server:** - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create and deploy a Connect server](/docs/connect/get-started/). - [Have a Jenkins instance up and running. ](https://www.jenkins.io/doc/) ## Get started To get started with the 1Password Secrets plugin for Jenkins: 1. [Install the 1Password Secrets plugin for Jenkins.](#install-plugin) 2. [Install 1Password CLI.](#step-2-install-1password-cli) 3. [Configure the 1Password Secrets plugin for Jenkins.](#configure-plugin) ### Step 1: Install the 1Password Secrets plugin for Jenkins {#install-plugin} You have several available options to install the 1Password Secrets plugin for Jenkins. You can use the Jenkins GUI (graphical user interface), the Jenkins CLI tool, or a direct upload. **Jenkins GUI:** To install the 1Password Secrets plugin for Jenkins using the GUI: 1. Sign in to your Jenkins instance. 2. From your Jenkins dashboard, go to **Manage Jenkins** > **Plugins**. 3. Select the **Available plugins** tab. 4. Search for *onepassword-secrets*. 5. Select the 1Password Secrets plugin for Jenkins, then select **Install**. Refer to [Use the GUI ](https://www.jenkins.io/doc/book/managing/plugins#from-the-web-ui) for more detailed instructions. **Jenkins CLI tool:** To install the 1Password Secrets plugin for Jenkins using the CLI tool: 1. Follow the [Use the CLI tool ](https://github.com/jenkinsci/plugin-installation-manager-tool) instructions. 2. Run the following command. Make sure to replace `1.0.0` with the correct version. ```sh jenkins-plugin-cli --plugins onepassword-secrets:1.0.0 ``` **Direct upload:** To install the 1Password Secrets plugin for Jenkins using a direct upload: 1. Download one of the [releases ](https://plugins.jenkins.io/onepassword-secrets#releases). 2. From your Jenkins dashboard, go to **Manage Jenkins** > **Plugins**. 3. Select the **Advanced** tab. 4. Select the `.hpi` file you downloaded from the release. 5. Select **Deploy**. Refer to [Use direct upload ](https://www.jenkins.io/doc/book/managing/plugins#advanced-installation) for more detailed instructions. ### Step 2: Install 1Password CLI The 1Password Secrets plugin for Jenkins relies on 1Password CLI. You must install 1Password CLI on the same machine that runs the Jenkins CI/CD pipeline. You can install 1Password CLI using a [Jenkinsfile ](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/) or using a Freestyle job. Either of these methods can install 1Password CLI in the same pipeline as the 1Password Secrets plugin for Jenkins or in a separate pipeline. :::info If you install 1Password CLI in the same pipeline, you will need to add the 1Password CLI installation script before you make any calls to the plugin. If you install 1Password CLI in a separate pipeline, you will need to set the **1Password CLI path** to the workspace where you performed the installation in your [configuration](#configuration). ::: **Jenkinsfile:** To install 1Password CLI using a Jenkinsfile: 1. Sign in to your Jenkins instance. 2. Select **New Item**. 3. Enter the job details, then select **Pipeline**. 4. Configure the job details. 5. Scroll to **Advanced Project Options** > **Pipeline**. 6. Select **Pipeline script**. 7. Add the code to install 1Password CLI to the **Script** field. You can install 1Password CLI with a Jenkinsfile using declarative or scripted [Jenkins pipeline syntax ](https://www.jenkins.io/doc/book/pipeline/syntax/). :::info The following examples show how to install 1Password CLI version 2.24 on a Linux amd64 machine. Make sure to change the example scripts to match your platform and use the [latest release of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2). ::: **Declarative Jenkinsfile:** ```groovy title="Declarative Jenkinsfile" pipeline { agent any stages { stage('Install 1Password CLI') { steps { sh 'curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip"' sh 'unzip -o op.zip -d op-dir' sh 'mv -f op-dir/op /usr/local/bin' sh 'rm -r op.zip op-dir' } } } } # code-result [Pipeline] Start of Pipeline [Pipeline] node Running on Jenkins in /config/workspace/Example [Pipeline] { [Pipeline] stage [Pipeline] { (Install 1Password CLI) [Pipeline] sh + curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip [Pipeline] sh + unzip -o op.zip -d op-dir Archive: op.zip extracting: op-dir/op.sig inflating: op-dir/op [Pipeline] sh + mv -f op-dir/op /usr/local/bin [Pipeline] sh + rm -r op.zip op-dir [Pipeline] } [Pipeline] // stage [Pipeline] } [Pipeline] // node [Pipeline] End of Pipeline Finished: SUCCESS ``` **Scripted Jenkinsfile:** ```groovy title="Scripted Jenkinsfile" node { stage('Install 1Password CLI') { sh ''' ARCH="amd64" curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_${ARCH}_v2.24.0.zip" unzip -o op.zip -d op-dir mv -f op-dir/op /usr/local/bin rm -r op.zip op-dir ''' } } # code-result [Pipeline] Start of Pipeline [Pipeline] node Running on Jenkins in /config/workspace/Test 1Password Secrets [Pipeline] { [Pipeline] stage [Pipeline] { (Install 1Password CLI) [Pipeline] sh + ARCH=amd64 + curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip + unzip -o op.zip -d op-dir Archive: op.zip extracting: op-dir/op.sig inflating: op-dir/op + mv -f op-dir/op /usr/local/bin + rm -r op.zip op-dir [Pipeline] } [Pipeline] // stage [Pipeline] } [Pipeline] // node [Pipeline] End of Pipeline Finished: SUCCESS ``` 8. Save the build. **Freestyle job:** :::warning[caution] Freestyle jobs don't let you set both the configuration and secrets at the job level. 1Password recommends using a Jenkinsfile rather than a Freestyle job. See [Migrating from chained Freestyle jobs to Pipelines ](https://www.jenkins.io/blog/2016/06/29/from-freestyle-to-pipeline/). ::: To install 1Password CLI using a Freestyle job: 1. Sign in to your Jenkins instance. 2. Select **New Item**. 3. Enter the job name, then select **Freestyle project**. 4. Configure the job details. 5. Scroll to **Build Steps**, then select **Add build step** > **Execute shell**. 6. Add the following commands to the **Execute shell** build step. ```shell ARCH="amd64" curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_${ARCH}_v2.24.0.zip" unzip -o op.zip -d op-dir mv -f op-dir/op /usr/local/bin rm -r op.zip op-dir # code-result Running as SYSTEM Building in workspace /config/workspace/Example [Test 1Password Secrets Freestyle] $ /bin/sh -xe /tmp/jenkins14763651031574634007.sh + ARCH=amd64 + curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip + unzip -o op.zip -d op-dir Archive: op.zip extracting: op-dir/op.sig inflating: op-dir/op + mv -f op-dir/op /usr/local/bin + rm -r op.zip op-dir Finished: SUCCESS ``` 7. Save the build. ### Step 3: Configure the 1Password Secrets plugin for Jenkins {#configure-plugin} You can configure the 1Password Secrets plugin for Jenkins from the Jenkins dashboard: 1. Login to your Jenkins instance. 2. Select **Manage Jenkins** > **System**. 3. Scroll to **1Password Secrets**. 4. Set the **1Password CLI path** to the location of the 1Password CLI executable. The example script uses `/usr/local/bin/op`. The remaining configuration steps depend on whether you use a service account or a Connect server. **Service account:** You must add at least one Service Account Credential to use a service account with the 1Password Secrets plugin for Jenkins. 1. Select **Add** > **Jenkins** under the Service Account Credential. 2. Set the **Domain**. 3. Set the **Kind** to **Secret text**.The plugin only supports [secret text ](https://www.jenkins.io/doc/book/pipeline/jenkinsfile#secret-text). 4. Set the **Scope**. 5. Set the **Secret** to the service account token. 6. You can leave the **ID** and **Description** empty. 7. Select **Add**. **Connect server:** You must specify the Connect Host value and add at least one Connect Credential to use a service account with the 1Password Secrets plugin for Jenkins. 1. Set **Connect Host** to the IP address, hostname, or URL of the Connect server. 2. Select **Add** > **Jenkins** under the Connect Credential. 3. Set the **Domain**. 4. Set the **Kind** to **Secret text**.The plugin only supports [secret text ](https://www.jenkins.io/doc/book/pipeline/jenkinsfile#secret-text). 5. Set the **Scope**. 6. Set the **Secret** to the Connect server token. 7. You can leave the **ID** and **Description** empty. 8. Select **Add**. For example configurations and pipeline scripts, go to [Usage examples](#usage-examples). :::info If you configure both a Connect server and a service account, the Connect server takes precedence. ::: ## Configuration The following sections document the available [configuration options](#configuration-options) and [configuration scopes](#configuration-scope). :::info If you install 1Password CLI in the same pipeline, you will need to add the 1Password CLI installation script before you make any calls to the plugin. If you install 1Password CLI in a separate pipeline, you will need to set the **1Password CLI path** to the workspace where you performed the installation in your [configuration](#configuration). ::: ### Configuration options The 1Password Secrets plugin for Jenkins has configuration options for 1Password CLI, Connect servers, and service accounts. | Setting | Description | | ------------------------------ | ------------------------------------------------------------ | | **Connect Host** | The hostname, IP address, or URL of the Connect server. | | **Connect Credential** | The [Connect server token](/docs/connect/security#connect-server-access-tokens) to authenticate with the Connect server. This setting is a [Jenkins secret text credential ](https://www.jenkins.io/doc/book/using/using-credentials/). | | **Service Account Credential** | The [service account token](/docs/service-accounts/security#service-accounts-and-token-generation) to authenticate with the service account. This setting is a [Jenkins secret text credential ](https://www.jenkins.io/doc/book/using/using-credentials). | | **1Password CLI path** | The path to the 1Password CLI executable. The default location is `/usr/local/bin/op` | ### Configuration scope You can configure the 1Password Secrets plugin for Jenkins globally, per folder, or per job. | Level | Description | | ------ | ------------------------------------------------------------ | | Global | Global-level configurations impact all jobs in all folders. To configure the 1Password Secrets plugin for Jenkins globally, add it to your global configuration. | | Folder | Folder-level configurations impact all jobs within the folder. To configure the 1Password Secrets plugin for Jenkins for a specific folder, add it to the folder configuration. | | Job | Job-level configurations only impact the jobs you configure. To configure the 1Password Secrets plugin for Jenkins for a single job, configure the plugin in the Jenkinsfile or Freestyle job. | The configuration priority is highest for job-level configurations and lowest for global configurations. The more specific the level, the higher the priority. This means you can have a default configuration at a broader level and override it at more specific levels. For example, if you configure a service account (service account A) globally, but override it with a different service account (service account B) in a job-level configuration, the job will use the second service account (service account B). :::info If you configure both a Connect server and a service account, the Connect server takes precedence. ::: ## Usage examples The following sections cover several use case examples for the 1Password Secrets plugin for Jenkins: - [Use with a Jenkinsfile](#use-with-a-jenkinsfile) - [Use with environment variables](#use-with-environment-variables) - [Use in a Freestyle job](#use-in-a-freestyle-job) ### Use with a Jenkinsfile You can access secrets within the Jenkins pipeline using [secret references](/docs/cli/secret-reference-syntax/) with the `withSecrets` function. This function receives the configuration and list of 1Password secrets and loads them as parameters. Explore the following examples to learn how to use the `withSecrets` function in various contexts. **About the configuration step...** **Service account:** The configuration at the beginning of the Jenkinsfile to configure the service account and 1Password CLI is optional. If you don't provide a configuration, the 1Password Secrets plugin uses a [more broadly scoped configuration](#configuration-scope). Make sure to replace service-account-token with the service account token and op-cli-path with the path you installed the 1Password CLI to (if you used a custom location). See [Configuration](#configuration). ```groovy [{ "badge": "🔴", "color": "red", "lineNo": 2, "substr": "service-account-token" }, { "badge": "🟢", "color": "green", "lineNo": 3, "substr": "op-cli-path" }] def config = [ serviceAccountCredentialId: 'service-account-token', opCLIPath: 'op-cli-path' ] ``` **Connect:** The configuration at the beginning of the Jenkinsfile to configure the Connect server and 1Password CLI is optional. If you don't provide a configuration, the 1Password Secrets plugin uses a [more broadly scoped configuration](#configuration-scope). Make sure to replace connect-server-token with the Connect server token, connect-host with the Connect server IP address, and op-cli-path with the path you installed the 1Password CLI to (if you used a custom location). See [Configuration](#configuration). ```groovy [{ "badge": "🔵", "color": "blue", "lineNo": 2, "substr": "connect-host" }, { "badge": "🟣", "color": "purple", "lineNo": 3, "substr": "connect-server-token" }, { "badge": "🟢", "color": "green", "lineNo": 4, "substr": "op-cli-path" }] def config = [ connectHost: 'connect-host', connectCredentialId: 'connect-server-token', opCLIPath: 'op-cli-path' ] ``` **Service account:** The following examples show how to use the `withSecrets` function in a Jenkinsfile with a 1Password Service Account. **Declarative Jenkinsfile:** The following [declarative Jenkinsfile ](https://www.jenkins.io/doc/book/pipeline/syntax#declarative-pipeline) shows how to use the `withSecrets` function with a service account. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. ```groovy title="Declarative Jenkinsfile" {18-23} [{ "badge": "🔴", "color": "red", "lineNo": 3, "substr": "service-account-token" }, { "badge": "🟢", "color": "green", "lineNo": 4, "substr": "op-cli-path" }] // Configure 1Password CLI and the service account. def config = [ serviceAccountCredentialId: 'service-account-token', opCLIPath: 'op-cli-path' ] // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`. def secrets = [ [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] ] pipeline { agent any stages{ stage('Push latest docker image') { steps { // Use the `withSecrets` function to access secrets. withSecrets(config: config, secrets: secrets) { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` **Scripted Jenkinsfile:** The following [scripted Jenkinsfile ](https://www.jenkins.io/doc/book/pipeline/syntax#scripted-pipeline) shows how to use the `withSecrets` function with a service account. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. ```groovy title="Scripted Jenkinsfile" {15-20} [{ "badge": "🔴", "color": "red", "lineNo": 4, "substr": "service-account-token" }, { "badge": "🟢", "color": "green", "lineNo": 5, "substr": "op-cli-path" }] node { // Configure 1Password CLI and the service account def config = [ serviceAccountCredentialId: 'service-account-token', opCLIPath: 'op-cli-path' ] // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`. def secrets = [ [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] ] stage('Push latest docker image') { // Use the `withSecrets` function to access secrets. withSecrets(config: config, secrets: secrets) { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } ``` **Connect server:** The following examples show how to use the `withSecrets` function in a Jenkinsfile with a 1Password Connect Server. **Declarative Jenkinsfile:** The following [declarative Jenkinsfile ](https://www.jenkins.io/doc/book/pipeline/syntax#declarative-pipeline) shows how to use the `withSecrets` function with a Connect server. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. ```groovy title="Declarative Jenkinsfile" {19-24} [{ "badge": "🔵", "color": "blue", "lineNo": 3, "substr": "connect-host" }, { "badge": "🟣", "color": "purple", "lineNo": 4, "substr": "connect-server-token" }, { "badge": "🟢", "color": "green", "lineNo": 5, "substr": "op-cli-path" }] // Configure 1Password CLI and the Connect server. def config = [ connectHost: 'connect-host', connectCredentialId: 'connect-server-token', opCLIPath: 'op-cli-path' ] // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`. def secrets = [ [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] ] pipeline { agent any stages{ stage('Push latest docker image') { steps { // Use the `withSecrets` function to access secrets. withSecrets(config: config, secrets: secrets) { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` **Scripted Jenkinsfile:** The following [scripted Jenkinsfile ](https://www.jenkins.io/doc/book/pipeline/syntax#scripted-pipeline) shows how to use the `withSecrets` function with a Connect server. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. ```groovy title="Scripted Jenkinsfile" {16-21} [{ "badge": "🔵", "color": "blue", "lineNo": 4, "substr": "connect-host" }, { "badge": "🟣", "color": "purple", "lineNo": 5, "substr": "connect-server-token" }, { "badge": "🟢", "color": "green", "lineNo": 6, "substr": "op-cli-path" }] node { // Configure 1Password CLI and the Connect server. def config = [ connectHost: 'connect-host', connectCredentialId: 'connect-server-token', opCLIPath: 'op-cli-path' ] // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`. def secrets = [ [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] ] stage('Push latest docker image') { // Use the `withSecrets` function to access secrets. withSecrets(config: config, secrets: secrets) { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } ``` :::tip Jenkins Pipeline Syntax helper You can also use the [Jenkins Pipeline Syntax helper](#use-in-a-freestyle-job) to create a pipeline script. ::: ### Use with environment variables The 1Password Secrets plugin for Jenkins lets you use [environment variables ](https://www.jenkins.io/doc/pipeline/tour/environment#using-environment-variables) to get configuration and secrets. The following examples show how to use environment variables with the 1Password Secrets plugin for Jenkins. You must set the environment variables in the `environment` block. The following table describes each environment variable. | Variable | Required | Description | | -------------------------- | ------------------------------------ | ------------------------------------------------------------ | | `OP_CLI_PATH` | Always required. | The path where you installed the 1Password CLI. If you followed the 1Password CLI installation instruction, set this value to `/usr/local/bin`.The example scripts on this page set this value to `op-cli-path`. | | `OP_SERVICE_ACCOUNT_TOKEN` | Required if using a service account. | The service account token of the service account to use.The example scripts on this page set this value to `service-account-token` variable. | | `OP_CONNECT_HOST` | Required if using a Connect server. | The IP address, hostname, or URL of the Connect server to use.The example scripts on this page set this value to `connect-server-host`. | | `OP_CONNECT_TOKEN` | Required if using a Connect server. | The Connect server token of the Connect server to use.The example scripts on this page set this value to `connect-server-token`. | If you don't configure these environment variables, the 1Password Secrets plugin uses a [more broadly scoped configuration](#configuration-scope). **Service account:** The following examples show how to use a service account with environment variables in a Jenkinsfile. **Declarative Jenkinsfile:** ```groovy title="Declarative Jenkinsfile" [{ "badge": "🔴", "color": "red", "lineNo": 5, "substr": "service-account-token" }, { "badge": "🟢", "color": "green", "lineNo": 6, "substr": "op-cli-path" }] pipeline { agent any environment { // Configure 1Password CLI and the service account. OP_SERVICE_ACCOUNT_TOKEN = credentials('service-account-token') OP_CLI_PATH = 'op-cli-path' // Define the environment variables using the secret reference `op://<vault>/<item>[/section]/<field>`. DOCKER_USERNAME = 'op://vault/item/username' DOCKER_PASSWORD = 'op://vault/item/password' } stages{ stage('Push latest docker image') { steps { // Access 1Password secrets. withSecrets() { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` **Scripted Jenkinsfile:** ```groovy title="Scripted Jenkinsfile" [{ "badge": "🟢", "color": "green", "lineNo": 4, "substr": "op-cli-path" }, { "badge": "🔴", "color": "red", "lineNo": 12, "substr": "service-account-token" }] node { def environment = [ // Configure 1Password CLI. 'OP_CLI_PATH = op-cli-path', // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`. 'DOCKER_USERNAME=op://vault/item/username', 'DOCKER_PASSWORD=op://vault/item/password' ] // Define the service account token. def credentials = [ string(credentialsId: 'service-account-token', variable: 'OP_SERVICE_ACCOUNT_TOKEN') ] withEnv(environment) { withCredentials(credentials) { stage('Push latest docker image') { // Use the `withSecrets` function to access secrets. withSecrets() { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` **Connect server:** The following examples show how to use a Connect server with environment variables in a Jenkinsfile. **Declarative Jenkinsfile:** ```groovy title="Declarative Jenkinsfile" [{ "badge": "🔵", "color": "blue", "lineNo": 5, "substr": "connect-host" }, { "badge": "🟣", "color": "purple", "lineNo": 6, "substr": "connect-server-token" }, { "badge": "🟢", "color": "green", "lineNo": 7, "substr": "op-cli-path" }] pipeline { agent any environment { // Configure 1Password CLI and the Connect server. OP_CONNECT_HOST = 'connect-host' OP_CONNECT_TOKEN = credentials('connect-server-token') OP_CLI_PATH = 'op-cli-path' // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`. DOCKER_USERNAME = 'op://vault/item/username' DOCKER_PASSWORD = 'op://vault/item/password' } stages{ stage('Push latest docker image') { steps { // Use the `withSecrets` function to access secrets. withSecrets() { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` **Scripted Jenkinsfile:** ```groovy title="Scripted Jenkinsfile" [{ "badge": "🔵", "color": "blue", "lineNo": 4, "substr": "connect-host" }, { "badge": "🟣", "color": "purple", "lineNo": 12, "substr": "connect-server-token" }, { "badge": "🟢", "color": "green", "lineNo": 5, "substr": "op-cli-path" }] node { def environment = [ // Configure 1Password CLI and the Connect server. 'OP_CONNECT_HOST=connect-host', 'OP_CLI_PATH = op-cli-path', // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op://<vault>/<item>[/section]/<field>`. 'DOCKER_USERNAME=op://vault/item/username', 'DOCKER_PASSWORD=op://vault/item/password' ] def credentials = [ string(credentialsId: 'connect-server-token', variable: 'OP_CONNECT_TOKEN') ] withEnv(environment) { withCredentials(credentials) { stage('Push latest docker image') { // Use the `withSecrets` function to access secrets. withSecrets() { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` ### Use in a Freestyle Job You can use the Jenkins Pipeline Syntax helper to set [environment variables ](https://www.jenkins.io/doc/pipeline/tour/environment#using-environment-variables) and access secrets in a Freestyle job. **Service account:** Use the Jenkins Pipeline Syntax helper to use a service account in a Freestyle job: 1. From the Freestyle job in Jenkins, go to the **Steps** section. 2. Set **1Password CLI path** to the location where you installed 1Password CLI. The example script uses `/usr/local/bin/op`. 3. Set **Service Account Credential** to the service account token. 4. Select **Add a 1Password secret**. 5. Set the **Environment variable** for the secret. 6. Set **Secret reference**. Use the [secret reference syntax](/docs/cli/secret-reference-syntax/) to point to the 1Password secret. 7. Select **Generate Pipeline Script**. **Connect server:** Use the Jenkins Pipeline Syntax helper to use a Connect server in a Freestyle job: 1. From the Freestyle job in Jenkins, go to the **Steps** section. 2. Set **1Password CLI path** to the location where you installed 1Password CLI. The example script uses `/usr/local/bin/op`. 3. Set **Connect Host** to the Connect server IP address or hostname. 4. Set **Connect Credential** to the Connect server token. 5. Select **Add a 1Password secret**. 6. Set the **Environment variable** for the secret. 7. Set **Secret reference**. Use [secret references](/docs/cli/secret-reference-syntax/) to point to the 1Password secret. 8. Select **Generate Pipeline Script**. --- ## 1Password CI/CD Integrations You can use 1Password integrations to securely access secrets from 1Password in your CI/CD pipeline without exposing any plaintext secrets in code, and rotate secrets without having to update your CI/CD environment. ## Get started Select the CI/CD tool you use to get started. All integrations support authentication with both [1Password Connect Servers](/docs/connect/) and [1Password Service Accounts](/docs/service-accounts/). --- ## Helm chart configuration This page documents the configuration options for the 1Password Helm charts: - [Connect and Operator Helm chart](#connect-and-operator-helm-chart) - [Secrets Injector Helm chart](#secrets-injector-helm-chart) ## Connect and Operator Helm chart The 1Password Connect and Operator Helm chart allows you to use Helm to deploy [Connect](/docs/connect/get-started/), the [Kubernetes Operator](/docs/k8s/operator/), or both. You can override configuration values in a chart with the `helm install` command using either the `--values` flag or the `--set` flag. You can also force a string value with the `--set-string` flag. For example, the following code block shows how to use the `--set` flag to set the `connect.applicationName` configuration value: ```shell helm install --set connect.applicationName=connect connect 1password/connect ``` Refer to the [official `helm install` documentation ](https://helm.sh/docs/helm/helm_install/) for more information. :::info By default, installing a 1Password Helm chart also installs the `OnePasswordItem` database operations for CRD (Custom Resource Definition). If you don't want to install the `OnePasswordItem` custom resource definitions (CRD), run `helm install` with the [`--skip-crds` flag ](https://helm.sh/docs/chart_best_practices/custom_resource_definitions#method-1-let-helm-do-it-for-you). ::: ### Configuration options The following table documents the available configuration options for the 1Password Connect and Operator Helm chart. :::tip If you have a large configuration value, use `--set-file` to read the single large value from the file (instead of `--values` or `--set`). For example: ``` $ helm install -f myvalues.yaml injector 1password/secrets-injector ``` ::: | Key | Type | Default | Description | | ------------------------------------- | ---------- | ---------------------------------- | ------------------------------------------------------------ | | `connect.create` | boolean | `true` | Denotes whether to deploy the 1Password Connect server. Set this value to `false` and `operator.create` to `true` to only deploy the Kubernetes Operator. See [Deploy without Connect](/docs/k8s/operator?deployment-type=helm#helm-step-2). | | `connect.replicas` | integer | `1` | The number of replicas to run the 1Password Connect deployment. | | `connect.applicationName` | string | `"onepassword-connect"` | The name of 1Password Connect application. | | `connect.host` | string | `"onepassword-connect"` | The name of 1Password Connect host. | | `connect.api.imageRepository` | string | `"1password/connect-api` | The 1Password Connect API repository. | | `connect.api.name` | string | `"connect-api"` | The name of the 1Password Connect API container. | | `connect.api.resources` | object | `{}` | The resources requests/limits for the 1Password Connect API pod. | | `connect.api.httpPort` | integer | `8080` | The port the Connect API is served on when not using TLS. | | `connect.api.httpsPort` | integer | `8443` | The port the Connect API is served on when using TLS. | | `connect.api.logLevel` | string | `info` | The log level of the Connect API container. Valid options are `trace`, `debug`, `info`, `warn`, and `error`. | | `connect.credentials` | jsonString | | The contents of the `1password-credentials.json` file for Connect. You can set it by adding `--set-file connect.credentials=<path/to/1password-credentials.json>` to your `helm install` command. | | `connect.credentials_base64` | string | | The base64-encoded contents of the `1password-credentials.json` file for Connect. You can use this instead of `connect.credentials` if supplying raw JSON to `connect.credentials` lead to issues. | | `connect.credentialsKey` | string | `"1password-credentials.json"` | The key for the 1Password Connect credentials (stored in the credentials secret). The credentials must be encoded as a base64 string. | | `connect.credentialsName` | string | `"op-credentials"` | The name of Kubernetes Secret containing the 1Password Connect credentials. | | `connect.dataVolume.name` | string | `"shared-data"` | The name of the shared [volume ](https://kubernetes.io/docs/concepts/storage/volumes/) used between 1Password Connect containers. | | `connect.dataVolume.type` | string | `"emptyDir"` | The type of shared [volume ](https://kubernetes.io/docs/concepts/storage/volumes/) used between 1Password Connect containers. | | `connect.dataVolume.values` | object | `{}` | Describes the fields and values for the configuration of the shared [volume ](https://kubernetes.io/docs/concepts/storage/volumes/) for 1Password Connect. | | `connect.imagePullPolicy` | string | `"IfNotPresent"` | The 1Password Connect API image pull policy. | | `connect.ingress.annotations` | object | `{}` | The 1Password Connect [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) annotations. | | `connect.ingress.enabled` | bool | `false` | Whether to enable 1Password Connect [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) traffic. | | `connect.ingress.extraPaths` | list | `[]` | Additional [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) paths. | | `connect.ingress.hosts[0].host` | string | `"chart-example.local"` | The 1Password Connect [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) hostname. | | `connect.ingress.hosts[0].paths` | list | `[]` | The 1Password Connect [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) path. | | `connect.ingress.ingressClassName` | string | `""` | Optionally use `ingressClassName` instead of a deprecated annotation. | | `connect.ingress.labels` | object | `{}` | [Ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) labels for 1Password Connect. | | `connect.ingress.pathType` | string | `"Prefix"` | Ingress [PathType ](https://kubernetes.io/docs/concepts/services-networking/ingress#path-types). | | `connect.ingress.tls` | list | `[]` | [Ingress TLS ](https://kubernetes.io/docs/concepts/services-networking/ingress#tls). | | `connect.nodeSelector` | object | `{}` | The [Node selector ](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node#nodeselector) stanza for the Connect pod. | | `connect.probes.readiness` | boolean | `true` | Denotes whether the 1Password Connect API readiness probe operates and ensures the pod is ready before serving traffic. | | `connect.probes.liveness` | boolean | `true` | Denotes whether Kubernetes continually checks the 1Password Connect API for liveness and restarts if the pod becomes unresponsive. | | `connect.annotations` | object | `{}` | Additional [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to add to the Connect API deployment resource. | | `connect.labels` | object | `{}` | Additional [labels ](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to add to the Connect API deployment resource. | | `connect.podAnnotations` | object | `{}` | Additional [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to be added to the Connect API pods. | | `connect.podLabels` | object | `{}` | Additional [labels ](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to be added to the Connect API pods. | | `connect.serviceType` | string | `NodePort` | The type of Service resource to create for the Connect API and Connect Sync services. | | `connect.serviceAnnotations` | object | `{}` | Additional [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to be added to the service. | | `connect.sync.imageRepository` | string | `"1password/connect-sync"` | The 1Password Connect Sync repository. | | `connect.sync.name` | string | `"connect-sync"` | The name of the 1Password Connect Sync container. | | `connect.sync.resources` | object | `{}` | The resources requests/limits for the 1Password Connect Sync pod. | | `connect.sync.httpPort` | integer | `8081` | The port serving the health of the Connect Sync container. | | `connect.sync.logLevel` | string | `info` | The log level of the Connect Sync container. Valid options are `trace`, `debug`, `info`, `warn`, and `error`. | | `connect.tls.enabled` | boolean | `false` | Denotes whether the Connect API is secured with TLS. | | `connect.tls.secret` | string | `"op-connect-tls"` | The name of the secret containing the TLS key (`tls.key`) and certificate (`tls.crt`). | | `connect.tolerations` | list | `[]` | A list of tolerations to be added to the Connect API pods. | | `connect.version` | string | `{{.Chart.AppVersion}}` | The 1Password Connect version to pull. | | `operator.autoRestart` | boolean | `false` | Denotes whether the Kubernetes Operator automatically restarts deployments based on associated updated secrets. See [Automatic redeployment](/docs/k8s/operator#enable-auto-redeployment). | | `operator.create` | boolean | `false` | Denotes whether to deploy the Kubernetes Operator. You can set this to `false` to only deploy Connect. | | `operator.imagePullPolicy` | string | `"IfNotPresent"` | The Kubernetes Operator image pull policy. | | `operator.imageRepository` | string | `"1password/onepassword-operator"` | The Kubernetes Operator repository. | | `operator.nodeSelector` | object | `{}` | [Node selector ](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node#nodeselector) stanza for the Kubernetes Operator pod. | | `operator.annotations` | object | `{}` | Additional [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to add to the Kubernetes Operator deployment resource. | | `operator.labels` | object | `{}` | Additional [labels ](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to be added to the Operator deployment resource. | | `operator.logLevel` | string | `info` | The log level of the Kubernetes Operator container. Valid options are: `debug`, `info`, and `error`. | | `operator.podAnnotations` | object | `{}` | Additional [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to add to the Kubernetes Operator pods. | | `operator.podLabels` | object | `{}` | Additional [labels ](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to add to the Kubernetes Operator pods. | | `operator.pollingInterval` | integer | `600` | The interval at which the Kubernetes Operator polls for secrets updates. | | `operator.clusterRole.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a cluster role for the Kubernetes Operator. | | `operator.clusterRole.name` | string | `"onepassword-connect-operator"` | The name of the Kubernetes Operator [Cluster Role ](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). | | `operator.clusterRoleBinding.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a [ClusterRole binding ](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) for the Kubernetes Operator Service Account. | | `operator.roleBinding.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a role binding for each Namespace for the Kubernetes Operator Service Account. | | `operator.roleBinding.name` | string | `"onepassword-connect-operator"` | The name of the Kubernetes Operator Role Binding. | | `operator.serviceAccount.annotations` | object | `{}` | The [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) for the 1Password Connect Service Account. | | `operator.serviceAccount.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a [Service Account](/docs/service-accounts/get-started/) for the Kubernetes Operator. | | `operator.serviceAccount.name` | string | `"onepassword-connect-operator"` | The name of the Kubernetes Operator. | | `operator.tolerations` | list | `[]` | A list of tolerations to add to the Kubernetes Operator pods. | | `operator.version` | string | `"1.8.0"` | The Kubernetes Operator version to pull. It defaults to the latest version. | | `operator.token.key` | string | `"token"` | The key for the 1Password Connect token (stored in the 1Password token secret). | | `operator.token.name` | string | `"onepassword-token"` | The name of Kubernetes Secret containing the 1Password Connect API token. | | `operator.token.value` | string | `"onepassword-token"` | An API token generated for 1Password Connect to be used by the Kubernetes Operator. | | `operator.watchNamespace` | list | `[]` | A list of namespaces for the Kubernetes Operator to watch and manage. Use the empty list to watch all namespaces. | | `operator.resources` | object | `{}` | The resources requests/limits for the Kubernetes Operator pod. | ## Secrets Injector Helm chart The 1Password Secrets Injector Helm chart allows you to use Helm to deploy the [Kubernetes Secrets Injector](/docs/k8s/injector/). You can override configuration values in a chart with the `helm install` command using either the `--values` flag or the `--set` flag. You can also force a string value with the `--set-string` flag. For example, the following code block shows how to use the `--set` flag to set the `injector.applicationName` configuration value: ```shell helm install --set injector.applicationName=injector injector 1password/secrets-injector ``` Refer to the [official `helm install` documentation ](https://helm.sh/docs/helm/helm_install/) for more information. ### Configuration options The following table documents the available configuration options for the Secrets Injector Helm chart. :::tip If you have a large configuration value, use `--set-file` to read the single large value from the file (instead of `--values` or `--set`). For example: ``` $ helm install -f myvalues.yaml injector 1password/secrets-injector ``` ::: | Key | Type | Default | Description | | -------------------------- | ------- | ----------------------------------------- | ------------------------------------------------------------ | | `injector.applicationName` | string | `"secrets-injector"` | The name of 1Password Kubernetes Secrets Injector Application. | | `injector.imagePullPolicy` | string | `"IfNotPresent"` | The 1Password Secrets Injector Docker image policy. `"IfNotPresent"` means the image is pulled only if it is not already present locally. | | `injector.imageRepository` | string | `"1password/kubernetes-secrets-injector"` | The 1Password Secrets Injector docker image repository. | | `injector.port` | string | `443` | The port the Secrets Injector exposes. | | `injector.targetPort` | integer | `8443` | The port the Secrets Injector API sends requests to the pod. | | `injector.version` | string | `{{.Chart.AppVersion}}` | The 1Password Secrets Injector version to pull. | --- ## 1Password Helm charts Helm is a tool that helps you manage Kubernetes applications through specification files called Helm charts. Helm charts define a Kubernetes application and make it easy to share, install, and upgrade. Refer to [Helm ](https://helm.sh) to learn more. The 1Password Helm charts allow you to use Helm to deploy a [Secrets Automation workflow](/docs/secrets-automation/). 1Password offers two Helm charts: - The [1Password Connect and Kubernetes Operator Helm chart ](https://github.com/1Password/connect-helm-charts/blob/main/charts/connect) runs a Connect server by itself or alongside the Kubernetes Operator. - The [1Password Secrets Injector Helm chart ](https://github.com/1Password/connect-helm-charts/blob/main/charts/secrets-injector) runs the Kubernetes Secrets Injector, which works with both service accounts and Connect servers. See the following comparison table to learn which Helm chart is right for the environment you want to run. | Environment | Connect and Operator | Secrets Injector | | ----------- | -------------------------------------- | -------------------------------------- | | Connect server (without the Kubernetes Operator) | Yes | No | | Connect server and the Kubernetes Operator | Yes | No | | Kubernetes Injector | No | Yes | ### Requirements Make sure you complete the requirements for the Helm chart you intend to use before continuing. **Connect Kubernetes Operator:** Before you use the 1Password Connect and Operator Helm chart, make sure you: Sign up for 1Password. Have a Kubernetes deployment. You can also use minikube to test locally. Install kubectl . Install Helm . Create a Secrets Automation workflow as a Connect server. **Kubernetes Secrets Injector:** Before you use the 1Password Kubernetes Secrets Injector Helm chart, make sure you: Sign up for 1Password. Have a Kubernetes deployment. You can also use minikube to test locally. Install kubectl . Install Helm . Create a Secrets Automation workflow as a Connect server or a service account. ### Deployment The deployment process for the 1Password Helm charts depends on multiple factors, including: - The type of secrets automation workflow. - Whether you want to use the Kubernetes Operator, the Kubernetes Injector, or neither. **Connect Kubernetes Operator:** There are multiple ways to use the Helm chart for 1Password Connect and the Kubernetes Operator. Select one to get started: 1. [Deploy a Connect server.](/docs/connect/get-started/?deploy-type=kubernetes#step-2-deploy-a-1password-connect-server) 2. [Deploy a Connect server and the Kubernetes Operator.](/docs/k8s/operator/?requirements=deploy-with-helm&deployment=helm#deployment) 3. [Deploy the Kubernetes Operator.](/docs/k8s/operator/?requirements=deploy-with-helm&deployment=helm#deployment) **Kubernetes Secrets Injector:** There are two ways to use the 1Password Connect and Operator Helm chart. Select one to get started: 1. [Deploy the Kubernetes Secrets Injector for a Connect server.](/docs/k8s/injector/?workflow-type=connect#deployment) 2. [Deploy the Kubernetes Secrets Injector for a service account.](/docs/k8s/injector/?workflow-type=service-account#deployment) ### Configuration See the [Helm chart configuration values reference](/docs/k8s/helm/) documentation. --- ## Kubernetes Injector The 1Password Kubernetes Secrets Injector implements a mutating webhook that allows you to inject 1Password secrets using a [service account](/docs/service-accounts/) or a [Connect server](/docs/connect/) to authenticate to 1Password. Unlike the 1Password [Kubernetes Operator](/docs/k8s/operator/), the Secrets Injector doesn't create a Kubernetes Secret when assigning secrets to your resource. See [Kubernetes integrations](/docs/k8s/integrations/) to compare the Kubernetes Operator and the Kubernetes Injector. :::tip Learn how to use the Kubernetes Secrets Injector with a 1Password Service Account. ::: ## Requirements Before using the Kubernetes Injector, make sure you: - [Sign up for 1Password](https://1password.com/pricing/password-manager). - Have a Kubernetes deployment. You can also use [minikube ](https://minikube.sigs.k8s.io/docs/start/) to test locally. - Create either a [service account](/docs/service-accounts/get-started/) or a [Connect server](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) to authenticate to 1Password. ## Limitations There are some limitations and nuances to consider about the Kubernetes Injector. For example: - The Kubernetes Injector requires deployment specifications to use the `command` field. - Secrets aren't available to all a container's sessions by default. ### The `command` field The Kubernetes Secrets Injector works by changing the `command` value on initialization. As a result, the pod you want to inject secrets into must have a `command` value defined in its [deployment specification ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) file (as shown in the following code block). See the `command` field in the code block below. In this example, a 1Password Service Account injects secrets into the application run by npm start. ```yaml [{ "badge": "1", "color": "sunbeam", "lineNo": 7, "substr": "npm" }, { "badge": "2", "color": "bitsblue", "lineNo": 8, "substr": "start" }] title="deployment-specification.yaml" spec: containers: - name: app-example1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_SERVICE_ACCOUNT_TOKEN valueFrom: secretKeyRef: name: op-service-account key: token - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password ``` If the deployments you're using aren't designed to have a command field specified in the deployment, then the 1Password [Kubernetes Operator](/docs/k8s/operator/) might be a better fit for your use case. ### Session availability Injected secrets are available only in the current pod's session. You can only access the secrets for the command listed in the container specification. To access it in any other session, for example, using `kubectl`, it's necessary to prepend `op run --` to the command. In the [service account example deployment specification](#usage-examples), the app-example1 container will have injected the `DB_USERNAME` and `DB_PASSWORD` values in the session executed by the command `npm start`. Another way to have secrets available in all sessions for a container is by using the [Kubernetes Operator](/docs/k8s/operator/). ## Deployment Use the following instructions to configure and deploy the Kubernetes Injector with your service account or Connect server and Kubernetes deployment. **Notes about strings and variables used in these code examples.** Some strings used throughout the code examples on this page are variable and arbitrary. Other strings have specific meanings within the context of 1Password. The following strings used in the code examples on this page have very specific and hard-coded meanings within the context of 1Password: - `OP_CONNECT_HOST` - `OP_CONNECT_TOKEN` - `OP_SERVICE_ACCOUNT_TOKEN` The following strings used in the code examples on this page have are variables and don't have specific meanings within the context of 1Password: - `DB_PASSWORD` - `DB_USERNAME` ### Step 1: Enable secrets injection Use kubectl to enable secrets injection by adding the `secrets-injection=enabled` label to your namespace (NAMESPACE) . The Kubernetes Injector uses the `default` namespace unless you specify a custom namespace. ```shell [{ "color": "lagoon", "lineNo": 1, "substr": "NAMESPACE" }] kubectl label namespace NAMESPACE secrets-injection=enabled ``` ### Step 2: Deploy the injector Use the `kubectl apply` command to the deployment specification files. When you use manual deployment, you must apply each deployment specification file separately. In the following example, INJECTOR.yaml is the name of the Kubernetes Injector deployment specification file and CONNECT.yaml is the name of the Connect deployment specification file. ```shell [{ "color": "tangerine", "lineNo": 1, "substr": "INJECTOR.yaml" },{ "color": "dahlia", "lineNo": 2, "substr": "CONNECT.yaml" }] kubectl apply -f INJECTOR.yaml kubectl apply -f CONNECT.yaml ``` To undeploy, use `kubectl delete`. ```shell [{ "color": "tangerine", "lineNo": 1, "substr": "INJECTOR.yaml" },{ "color": "dahlia", "lineNo": 2, "substr": "CONNECT.yaml" }] kubectl delete -f INJECTOR.yaml kubectl delete -f CONNECT.yaml ``` The commands in this example only deploy the Kubernetes Injector and Connect. They don't handle additional configuration you might need, like [permissions ](https://kubernetes.io/docs/tasks/administer-cluster/securing-a-cluster/), [namespaces ](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), and [custom resource definitions (CRD) ](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). :::tip You can deploy and configure the Kubernetes Injector in one command if you use the [1Password Secrets Injector Helm chart](/docs/k8s/helm/). ::: :::info The Kubernetes Injector creates the necessary [TLS certificate ](https://en.wikipedia.org/wiki/Public_key_certificate) for the webhook when it's deployed ([`deployment.yaml` ](https://github.com/1Password/kubernetes-secrets-injector/blob/main/deploy/deployment.yaml)). If you remove the Kubernetes Injector from the cluster, it automatically deletes the TLS certificate. ::: ### Step 3: Annotate your deployment specification Annotate your [Kubernetes deployment specification ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) with `operator.1password.io/inject:` followed by a comma-separated list of the containers you want to mutate and inject secrets into. 1. Edit your deployment specification file and add the following annotation: ```yaml title="deployment-specification.yaml" annotations: operator.1password.io/inject: "app-example1, app-example2" ``` ### Step 4: Configure the resource environment Add an environment variable to your pod or [Kubernetes deployment specification ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) with a value referencing your 1Password item using a [secret reference](/docs/cli/secret-reference-syntax/). 1. Edit your deployment specification file and add an environment variable containing the path to the 1Password item. Make sure to replace VAULT , ITEM, SECTION, and FIELD with the correct values. ```yaml [{ "color": "tangerine", "lineNo": 3, "substr": "VAULT" }, { "color": "dahlia", "lineNo": 3, "substr": "ITEM" }, { "color": "sunbeam", "lineNo": 3, "substr": "SECTION" }, { "color": "bitsblue", "lineNo": 3, "substr": "FIELD" }] title="deployment-specification.yaml" env: - name: DB_USERNAME value: op://VAULT/ITEM[/SECTION]/FIELD ``` The value should look something like the text in the following code block: ```yaml title="deployment-specification.yaml" env: - name: DB_USERNAME value: op://my-vault/sql/username ``` ### Step 5: Add your 1Password credentials to your deployment #### Step 5.1: Create a Kubernetes Secret with your authentication token To authenticate to 1Password, you'll need to create a [Kubernetes Secret ](https://kubernetes.io/docs/concepts/configuration/secret/) that contains your service account or Connect server token. **Service account:** You can pass your service account token to Kubernetes using the `kubectl create secret` command: :::note Your service account token is generated automatically during the service account creation process. If you lose the token, you must [create a new service account](/docs/service-accounts/get-started/). ::: ```shell [{ "color": "bitsblue", "lineNo": 1, "substr": "YOUR_SERVICE_ACCOUNT_TOKEN" }] kubectl create secret generic op-service-account --from-literal=token=YOUR_SERVICE_ACCOUNT_TOKEN ``` This creates a generic Secret named `op-service-account` with a key named `token` that contains your service account token. **Connect:** You can pass your Connect server access token token to Kubernetes using the `kubectl create secret` command: ```shell [{ "color": "bitsblue", "lineNo": 1, "substr": "YOUR_CONNECT_TOKEN" }] kubectl create secret generic connect-token --from-literal=token=YOUR_CONNECT_TOKEN ``` This creates a generic Secret named `connect-token` with a key named `token` that contains your Connect server access token. #### Step 5.2: Add the Secret to your Kubernetes deployment specification file You can reference the Secret you created for your service account or Connect server token in your [Kubernetes deployment specification file ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) using an environment variable. Kubernetes will automatically inject the authentication token into your pod or deployment when it starts. **Service account:** Add an environment variable named `OP_SERVICE_ACCOUNT_TOKEN` to your deployment specification file, and set the `valueFrom` to reference the Kubernetes Secret you created in the previous step. If you used a custom Secret or key name, make sure to update the example to use the appropriate name and key. ```yaml [{ "color": "tangerine", "lineNo": 13, "substr": "op-service-account" }, { "color": "bitsblue", "lineNo": 14, "substr": "token" }] title="deployment-specification.yaml" spec: containers: - name: app-example1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_SERVICE_ACCOUNT_TOKEN valueFrom: secretKeyRef: name: op-service-account key: token ``` **Connect:** 1. Add an environment variable named `OP_CONNECT_HOST` to your deployment specification file for your Connect server host. Set the `value` to the URL where your Connect server is deployed. 2. Add an environment variable named `OP_CONNECT_TOKEN`, and set the `valueFrom` to reference the Kubernetes Secret you created in the previous step. If you used a custom Secret or key name, make sure to update the example to use the appropriate name and key. ```yaml [{ "color": "tangerine", "lineNo": 15, "substr": "connect-token" }, { "color": "bitsblue", "lineNo": 16, "substr": "token" }] title="deployment-specification.yaml" spec: containers: - name: app-example1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_CONNECT_HOST value: http://onepassword-connect:8080 - name: OP_CONNECT_TOKEN valueFrom: secretKeyRef: name: connect-token key: token ``` :::caution If you configure the Kubernetes Injector to authenticate with both a service account and a Connect server, the Connect server will take precedence. ::: ## Usage examples The following Kubernetes deployment specification files show what your deployment file should look like. **Service account:** The following code block contains an example of a Kubernetes deployment specification YAML file setup to inject secrets using a 1Password Service Account. In this example, the Kubernetes Injector injects secrets into APP_1, but not APP_2. ```yaml [{ "color": "sunbeam", "lineNo": 12, "substr": "APP_1" },{ "color": "sunbeam", "lineNo": 17, "substr": "APP_1" }, { "color": "tangerine", "lineNo": 33, "substr": "APP_2" }] title="deployment-specification.yaml" apiVersion: apps/v1 kind: Deployment metadata: name: app-example spec: selector: matchLabels: app: app-example template: metadata: annotations: operator.1password.io/inject: APP_1 labels: app: app-example spec: containers: - name: APP_1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_SERVICE_ACCOUNT_TOKEN valueFrom: secretKeyRef: name: op-service-account key: token - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password - name: APP_2 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password ``` **Connect:** The following code block contains an example of a Kubernetes deployment specification YAML file setup to inject secrets using a 1Password Connect Server. In this example, the Kubernetes Injector injects secrets into APP_1, but not APP_2. ```yaml [{ "color": "sunbeam", "lineNo": 12, "substr": "APP_1" },{ "color": "sunbeam", "lineNo": 17, "substr": "APP_1" }, { "color": "tangerine", "lineNo": 35, "substr": "APP_2" }] title="deployment-specification.yaml" apiVersion: apps/v1 kind: Deployment metadata: name: app-example spec: selector: matchLabels: app: app-example template: metadata: annotations: operator.1password.io/inject: APP_1 labels: app: app-example spec: containers: - name: APP_1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_CONNECT_HOST value: http://onepassword-connect:8080 - name: OP_CONNECT_TOKEN valueFrom: secretKeyRef: name: connect-token key: token-value - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password - name: APP_2 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password ``` --- ## Kubernetes integrations You can use Kubernetes integrations to deploy a [1Password Connect Server](/docs/connect/) or a [1Password Service Account](/docs/service-accounts/) to a Kubernetes cluster. 1Password offers multiple Kubernetes integrations, including the [Kubernetes Secrets Injector](#kubernetes-injector), the [Kubernetes Operator](#kubernetes-operator), and [Helm charts](#1password-helm-charts) (which support both the Kubernetes Injector and the Kubernetes Operator). The best integration option depends on your unique environment. ## Comparison Both the Kubernetes Injector and the Kubernetes Operator work by allowing you to inject secrets from 1Password into a Kubernetes environment. However, they vary slightly based on your intended use case and their requirements. The 1Password Helm charts allow you to more easily deploy a Connect server, the Kubernetes Operator, or the Kubernetes Injector. Refer to the following table to learn the differences between the integrations. | **Feature** | [**Kubernetes Injector**](#kubernetes-injector) | [**Kubernetes Operator**](#kubernetes-operator) | | ----------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------- | | Supports service accounts | Yes | Yes | | Supports Connect servers | Yes | Yes | | Allows for granular selection of secrets | Yes | No | | Uses Kubernetes Secrets | No | Yes | | Injects 1Password items directly into Kubernetes pods | Yes | No | | Works with multiple credentials simultaneously | Yes | No | | Supports automatic redeployment when 1Password items change | No | Yes | | Requires a Connect token to deploy | No | Yes | ### Kubernetes Injector The 1Password Kubernetes Secrets Injector implements a mutating webhook that allows you to inject 1Password secrets as environment variables into a Kubernetes pod or deployment. You can use the Kubernetes Injector with [Connect servers](/docs/connect/) or [service accounts](/docs/service-accounts/). Get started with the Kubernetes Injector ### Kubernetes Operator The 1Password Connect Kubernetes Operator integrates [Kubernetes Secrets ](https://kubernetes.io/docs/concepts/configuration/secret/) with 1Password with one or more Connect servers or service accounts. It allows you to: - Create Kubernetes Secrets from 1Password items and load them into Kubernetes deployments. - Automatically restart deployments when 1Password items update. Get started with the Kubernetes Operator ### 1Password Helm charts [Helm ](https://helm.sh/) is a tool that helps you manage Kubernetes applications through specification files called Helm charts. Helm charts define a Kubernetes application and make it easy to share, install, and upgrade. The official 1Password Helm charts allow you to create a Secrets Automation workflow deployment using a predefined specification. Get started 1Password Helm charts --- ## Kubernetes Operator The 1Password Connect Kubernetes Operator integrates [Kubernetes Secrets ](https://kubernetes.io/docs/concepts/configuration/secret/) with 1Password with one or more Connect servers. It allows you to: - Create Kubernetes Secrets from 1Password items and load them into Kubernetes deployments. - Automatically restart deployments when 1Password items update. ## Requirements Before using the Kubernetes Operator, make sure you finish the requirement steps. The requirements vary slightly depending on how you plan to deploy the Kubernetes Operator. **Deploy with Helm:** Before you can deploy the Kubernetes Operator with the 1Password Connect and Operator Helm chart, you must: Sign up for 1Password. Install 1Password CLI. Have a Kubernetes deployment. You can also use minikube to test locally. Install Helm . Create a Secrets Automation workflow as a Connect server. You need the Connect server's `1password-credentials.json` file. **Deploy manually with Connect:** Before you can deploy the Kubernetes Operator with a Kubernetes deployment specification file, you must: Sign up for 1Password. Install 1Password CLI. Have a Kubernetes deployment. You can also use minikube to test locally. Create a Secrets Automation workflow as a Connect server. You need the Connect server's `1password-credentials.json` file. **Deploy manually with a service account:** Before you can deploy the Kubernetes Operator with a service account, you must: Sign up for 1Password. Have a Kubernetes deployment. You can also use minikube to test locally. ## Limitations The Kubernetes Operator supports Connect servers and service accounts. Additionally, the Operator doesn't allow you to select secrets granularly or use multiple credentials simultaneously. For a complete comparison of features and functionality, see [Kubernetes integrations](/docs/k8s/integrations/). ## Deployment There are two ways to deploy the Kubernetes Operator: 1. Using the 1Password Connect and Operator Helm chart. 2. Manually using a Kubernetes deployment specification file. :::warning[caution] The recommended way to deploy the Kubernetes Operator is with Helm. Deploying manually is a much more involved and complicated process. ::: **Deploy with Helm:** The following instructions cover deploying the Kubernetes Operator using the [1Password Connect and Operator Helm chart](/docs/k8s/helm/). You can use the 1Password Connect and Operator Helm chart to deploy the Kubernetes alongside Connect or without Connect. ### Step 1. Add the 1Password Helm chart repository {#helm-step-1} The following command adds the [1Password Helm chart repository ](https://github.com/1Password/connect-helm-charts) to your local instance of Helm. This allows you to download and install all charts from 1Password's GitHub repository. ```shell helm repo add 1password https://1password.github.io/connect-helm-charts/ ``` ### Step 2. Install the Kubernetes Operator using Helm {#helm-step-2} You can use the 1Password Connect and Operator Helm chart to deploy the Kubernetes Operator with Connect or without Connect. In most cases, it makes sense to deploy the Kubernetes Operator alongside Connect because it simplifies the setup and communication between Connect and the Operator. However, it might make more sense to deploy only the Kubernetes Operator if you already have a Connect deployment in production. **With Connect:** To install the Kubernetes Operator with Connect, use the following command. It deploys the Kubernetes Operator with a 1Password Connect server using the `1password-credentials.json` file. ```shell [{ "color": "tangerine", "lineNo": 1, "substr": "OP_CONNECT_TOKEN" }] helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json --set operator.create=true --set operator.token.value=OP_CONNECT_TOKEN ``` If you don't already have a Connect token, use the following command instead. Make sure to replace SERVER and VAULT with the correct values. ```shell [{ "color": "sunbeam", "lineNo": 1, "substr": "SERVER" },{ "color": "dahlia", "lineNo": 1, "substr": "VAULT" }] helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json --set operator.create=true --set operator.token.value=$(op connect token create --server SERVER --vault VAULT) ``` **Without Connect:** To install the Kubernetes Operator without Connect, set `operator.create` to `true` and `connect.create` to `false`. ```shell helm install connect 1password/connect --set operator.create=true --set operator.token.value=<token> --set connect.create=false ``` If you don't already have a Connect token, use the following command instead. Make sure to replace SERVER and VAULT with the correct values. ```shell [{ "color": "sunbeam", "lineNo": 1, "substr": "SERVER" },{ "color": "dahlia", "lineNo": 1, "substr": "VAULT" }] helm install connect 1password/connect --set operator.create=true --set operator.token.value=$(op connect token create --server SERVER --vault VAULT) --set connect.create=false ``` **With a service account:** To install the Kubernetes Operator with a service account, set `operator.create` to `true`, `connect.create` to `false`, and `operator.authMethod` to `service-account`. ```shell helm install connect 1password/connect --set operator.create=true --set connect.create=false --set operator.authMethod=service-account --set operator.serviceAccountToken.value=<token> ``` **Deploy manually with Connect:** The following instructions cover deploying the Kubernetes Operator manually, using a [Kubernetes deployment specification ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). 1. [Create a deployment specification.](#manual-step-1) 2. [Create a Kubernetes Secret from the Connect server credentials.](#manual-step-2) 3. [Add the `MANAGE_CONNECT` environment variable.](#manual-step-3) 4. [Create a Kubernetes Secret for the Connect server token.](#manual-step-4) 5. [Deploy the Kubernetes Operator.](#manual-step-5) ### Step 1: Create a deployment specification {#manual-step-1} 1. Create a [Kubernetes deployment specification ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) YAML file. You can use the example [`manager.yaml` ](https://github.com/1Password/onepassword-operator/blob/main/config/manager/manager.yaml) file from the Kubernetes Operator repository on GitHub. You can also update an existing Kubernetes deployment specification to include the `1password/onepassword-operator` container image and options. ### Step 2: Create a Kubernetes Secret from the Connect server credentials {#manual-step-2} 1. Encode the `1password-credentials.json` file you generated when you created your Connect server and name it FILE_NAME. ```shell [{ "color": "lagoon", "lineNo": 1, "substr": "FILE_NAME"}] cat 1password-credentials.json | base64 | \ tr '/+' '_-' | tr -d '=' | tr -d '\n' > FILE_NAME ``` 2. Use `kubectl` to create a Kubernetes Secret from the encoded FILE_NAME file. ```shell [{ "color": "lagoon", "lineNo": 1, "substr": "FILE_NAME"}] kubectl create secret generic op-credentials --from-file=FILE_NAME ``` ### Step 3: Add the `MANAGE_CONNECT` environment variable {#manual-step-3} 1. Add the `MANAGE_CONNECT` environment variable to the Kubernetes Operator container (`onepassword-connect-operator`) in the deployment specification file and set it to `true`. The `MANAGE_CONNECT` environment variable tells the Kubernetes Operator to automatically deploy a default configuration of the 1Password Connect server to the current namespace. ```yaml title="deployment-specification.yaml" - name: MANAGE_CONNECT value: "true" ``` ### Step 4: Create a Kubernetes Secret for the Connect server token {#manual-step-4} Create a Kubernetes Secret for your Connect server token. Replace OP_CONNECT_TOKEN with the Connect token string or an environment variable that contains the Connect token string. ```shell [{ "color": "bitsblue", "lineNo": 1, "substr": "OP_CONNECT_TOKEN"}] kubectl create secret generic onepassword-token --from-literal=token="OP_CONNECT_TOKEN" ``` :::tip If you don't already have a Connect server token for the Kubernetes Operator, you can use the following command to create a token and save it as a Kubernetes Secret. ```shell [{ "color": "bitsblue", "lineNo": 1, "substr": "SERVER"}, { "color": "sunbeam", "lineNo": 1, "substr": "VAULT"}] kubectl create secret generic onepassword-token --from-literal=token=$(op connect token create op-k8s-operator --server SERVER --vault VAULT) ``` Make sure to replace SERVER with the name (or ID) of the Connect server and VAULT with the name (or ID) of the vault. ::: ### Step 5: Deploy the Kubernetes Operator and Connect server {#manual-step-5} Finally, manually deploy the Kubernetes Operator by running `make deploy`. :::warning[caution] You must clone the [Kubernetes Operator repository ](https://github.com/1Password/onepassword-operator) before you can manually deploy the Kubernetes Operator. ::: 1. Clone the [Kubernetes Operator repository ](https://github.com/1Password/onepassword-operator). 2. Run `make deploy`. :::tip Run the following command to check if the CRDs installed correctly: ```shell kubectl get crd onepassworditems.onepassword.com ``` ::: **Deploy manually with a service account:** To deploy the Kubernetes Operator with a service account, first [create a service account](/docs/service-accounts/get-started#create-a-service-account). Then follow these steps: ### 1. Create a Kubernetes secret for the service account 1. Set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to the service account token you created in step 1. This token will be used by the Operator to access 1Password items. 2. Create a Kubernetes secret: ```shell kubectl create secret generic onepassword-service-account-token --from-literal=token="$OP_SERVICE_ACCOUNT_TOKEN" ``` ### 2. Deploy the Operator To use the Operator with a service account, you need to set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable in the `/config/manager/manager.yaml` file and remove the environment variables `OP_CONNECT_TOKEN` and `OP_CONNECT_HOST`. To configure the 1Password Kubernetes Operator, the following environment variables can be set in the Operator YAML file: - `OP_SERVICE_ACCOUNT_TOKEN` (required): Specifies a service account token within Kubernetes to access the 1Password items. - `WATCH_NAMESPACE`: A comma-separated list of namespaces to watch for changes. The default is `watch all namespaces`. - `POLLING_INTERVAL`: The number of seconds the 1Password Kubernetes Operator will wait before checking for updates from 1Password. The default is `600`. - `AUTO_RESTART`: If set to true, the Operator will restart any deployment using a secret from 1Password. This can be overwritten by a namespace, deployment, or individual secret. The default is `false`. After you've set the environment variables, run the following command to deploy the Operator: ```shell make deploy ``` You can view a sample YAML file [in the onepassword-operator repository on GitHub. ](https://github.com/1Password/onepassword-operator/blob/main/config/manager/manager.yaml) ## Usage examples Use the following usage examples to help you get started: - [Create a Kubernetes Secret from a 1Password item](#kubernetes-secret-from-item) - [Deploy with a single Kubernetes Secret](#deploy-single) - [Ignore updates for a Kubernetes Secret](#ignore-updates) - [Enable automatic redeployment](#enable-auto-redeployment) - [Per Kubernetes Operator](#per-kubernetes-operator) - [Per namespace](#per-namespace) - [Per Kubernetes deployment](#per-kubernetes-deployment) - [Per OnePasswordItem](#per-onepassworditem) ### Create a Kubernetes Secret from a 1Password item {#kubernetes-secret-from-item} With the Kubernetes Operator deployed, you can create [Kubernetes Secrets ](https://kubernetes.io/docs/concepts/configuration/secret/) from 1Password items by creating a YAML file and then using `kubectl` to deploy it to your Kubernetes cluster. The YAML file tells the Kubernetes Operator to create a Kubernetes Secret from a `OnePasswordItem` (a 1Password item) and specifies the item name and the path of the item. 1. Create a YAML file (`1password-item.yaml`) for the 1Password item using the following template. Replace `SECRET_NAME`, `VAULT`, and `ITEM` with the correct values for your 1Password item. - Replace SECRET_NAME with the name to use to create the Kubernetes Secret. - Replace VAULT with the name or ID of the vault. - Replace ITEM with the ID or title of the 1Password item. ```yaml title="1password-item.yaml" [{ "color": "dahlia", "lineNo": 4, "substr": "SECRET_NAME" }, { "color": "sunbeam", "lineNo": 6, "substr": "VAULT" }, { "color": "bitsblue", "lineNo": 6, "substr": "ITEM" }] apiVersion: onepassword.com/v1 kind: OnePasswordItem metadata: name: SECRET_NAME spec: itemPath: "vaults/VAULT/items/ITEM" ``` 1. Use `kubectl` to deploy the `1password-item.yaml` file. ```shell kubectl apply -f 1password-item.yaml ``` ```shell kubectl get secret 1password-item.yaml ``` :::warning[caution] If you delete the 1Password item you created, the Kubernetes Operator automatically deletes the corresponding Kubernetes Secret. ::: #### Deploy with a single Kubernetes Secret {#deploy-single} You can also create a single Kubernetes Secret for a Kubernetes deployment by adding specific metadata to the deployment specification file and then applying it. 1. Add the following annotations to the deployment specification file: ```yaml title="deployment-specification.yaml" [{"badge": "🟣", "color": "dahlia", "lineNo": 6, "substr": "VAULT" }, { "color": "bitsblue", "lineNo": 6, "substr": "ITEM" }, { "color": "tangerine", "lineNo": 7, "substr": "SECRET_NAME" }] apiVersion: apps/v1 kind: Deployment metadata: name: deployment-example annotations: operator.1password.io/item-path: "vaults/VAULT/items/ITEM" operator.1password.io/item-name: "SECRET_NAME" ``` Replace `VAULT`, `ITEM`, and `SECRET_NAME`, with the correct values for your 1Password item. - Replace VAULT with the name or ID of the vault. - Replace ITEM with the ID or title of the 1Password item. - Replace SECRET_NAME with the name to use to create the Kubernetes Secret. 2. Apply the YAML file. This creates a Kubernetes Secret named SECRET_NAME with the content from the 1Password item specified in the `operator.1password.io/item-path`. ```shell kubectl apply -f deployment-specification.yaml ``` ### Ignore updates for a Kubernetes Secret {#ignore-updates} The Kubernetes Operator automatically keeps Kubernetes Secrets in sync with the corresponding 1Password items. If a 1Password Item linked to a Kubernetes Secret changes within the `POLLING_INTERVAL`, the associated Kubernetes Secret automatically updates. You can prevent a specific Kubernetes Secret from updating by adding the annotation `operator.1password.io:ignore-secret` to the item stored in 1Password. While this annotation is in place, the Kubernetes Secret won't update when the associated 1Password item updates. ### Enable automatic redeployment {#enable-auto-redeployment} The Kubernetes Operator supports automatic redeployment, which automatically restarts Kubernetes deployments when it detects that a 1Password item linked to a Kubernetes Secret has been updated. When enabled, the Kubernetes Operator restarts Kubernetes deployments that meet the following criteria each time the Connect server polls for updates: - Its scope is configured to automatically restart. - It's using a Kubernetes Secret linked to a 1Password item that's been updated. You can configure automatic redeployment for different scopes: - [Per Kubernetes Operator](#per-kubernetes-operator) - [Per namespace](#per-namespace) - [Per Kubernetes deployment](#per-kubernetes-deployment) - [Per OnePasswordItem](#per-onepassworditem) When you configure automatic deployment in a scope (such as per namespace), the configuration applies to all downstream scopes unless you explicitly specify a different configuration for the scope. #### Per Kubernetes Operator You can configure automatic redeployment per Kubernetes Operator, which includes all Kubernetes deployments within the namespaces watched by the Kubernetes Operator instance. The Kubernetes Operator automatic redeployment setting is controlled by the `AUTO_RESTART` environment variable. By default, it's set to `false`. To enable automatic redeployment, set it to `true`. #### Per namespace You can configure automatic redeployment per namespace, which includes all Kubernetes deployments within the namespace. - To turn on automatic redeployment for all Kubernetes deployments within a namespace, set the `operator.1password.io/auto-restart` annotation to `true`. - To turn off automatic redeployment for all Kubernetes deployments within a namespace, set the `operator.1password.io/auto-restart` annotation to `false`. Each namespace uses the Kubernetes Operator setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value. The following code block shows an example namespace configuration with automatic redeployment enabled for all Kubernetes deployments within the namespace. ```yaml title="deployment-specification.yaml" {6} apiVersion: v1 kind: Namespace metadata: name: "example-namespace" annotations: operator.1password.io/auto-restart: "true" ``` #### Per Kubernetes deployment You can configure automatic redeployment per individual Kubernetes deployment: - To turn on automatic redeployment for a specific Kubernetes deployment, set the `operator.1password.io/auto-restart` annotation to `true`. - To turn off automatic redeployment for a specific Kubernetes deployment, set the `operator.1password.io/auto-restart` annotation to `false`. Each Kubernetes deployment uses the namespace setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value. The following code block shows an example deployment configuration with automatic redeployment enabled. ```yaml title="deployment-specification.yaml" {6} apiVersion: v1 kind: Deployment metadata: name: "example-deployment" annotations: operator.1password.io/auto-restart: "true" ``` #### Per OnePasswordItem You can configure automatic redeployment for a specific 1Password item (`OnePasswordItem`) custom resource: - To turn on automatic redeployment for a specific 1Password item custom resource, set the `operator.1password.io/auto-restart` annotation value to `true`. - To turn off automatic redeployment for a specific 1Password item custom resource, set the `operator.1password.io/auto-restart` annotation value to `false`. Each 1Password item (`OnePasswordItem`) uses the Kubernetes deployment setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value. The following code block shows an example of a 1Password item configuration with automatic redeployment enabled. ```yaml title="deployment-specification.yaml" {6} apiVersion: onepassword.com/v1 kind: OnePasswordItem metadata: name: example annotations: operator.1password.io/auto-restart: "true" ``` ## Behavior The 1Password Kubernetes Connect Operator follows the Kubernetes Operator pattern. It uses Controllers, which provide a reconcile function that synchronizes resources until it reaches the desired cluster state. Visit the Kubernetes documentation to learn more about the [Operator pattern ](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) and [Controllers ](https://kubernetes.io/docs/concepts/architecture/controller/). The information in this section documents some of the behavior of the Kubernetes Operator in specific scenarios. - [Deployment deletion](#deployment-deletion) - [Fields storing files](#fields-storing-files) - [Whitespace characters](#whitespace-characters) ### Deployment deletion Deleting the Deployment you've created deletes the Kubernetes Secret deployment if all the following are true: 1. The deployment has the `operator.1password.io/item-path` and `operator.1password.io/item-name` annotations. 2. No other deployments are using the secret. ### Fields storing files If a 1Password item field stores a file, the corresponding Kubernetes Secret uses the file's contents as the value. If a single 1Password item has a field storing a file and a field storing another type of data, the Kubernetes Operator prefers the non-file field and ignores the field containing a file. ### Whitespace characters Titles and field names that include whitespace characters (or any other characters invalid for DNS subdomain names) result in the Kubernetes Operator changing the titles (or fields) in the following manner when creating Kubernetes Secrets: - Remove invalid characters before the first alphanumeric character. - Remove invalid characters after the last alphanumeric character. - Replace whitespace characters between words with a dash (`-`). - Convert letters to lowercase. ## Configuration The following section describes the Kubernetes Operator (`1password/onepassword-operator`) container configuration options and their default values. The [example Kubernetes deployment specification file ](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure#define-container-environment-variables-using-secret-data) shows these configuration values in context. ### Environment variables | **Environment variable** | **Description** | **Required** | **Default value** | | ------------------------ | ------------------------------------------------------------ | ------------ | ------------------------------------------------------------ | | `OP_CONNECT_HOST` | The hostname of the Connect server within Kubernetes. | Yes | `http://onepassword-connect:8080` | | `WATCH_NAMESPACE` | A comma-separated list of namespaces to watch for changes. By default, it watches all namespaces. | No | default (watch all namespaces) | | `POLLING_INTERVAL` | The number of seconds the Kubernetes Operator should wait before checking for updates from the Connect server. | No | `600` | | `MANAGE_CONNECT` | Whether or not the Kubernetes Operator should deploy with the Connect server in the current namespace with the default configuration. | No | `false` | | `AUTO_RESTART` | Whether or not the Kubernetes Operator should redeploy when it detects a secret change from the Connect server. You can overwrite this value by namespace, deployment, or individual secret. | No | `false` | | `OP_CONNECT_TOKEN` | A reference to the Kubernetes Secret that contains your Connect server token. | Yes | [secretKeyRef ](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure#define-container-environment-variables-using-secret-data) | ### Command arguments | **Argument** | **Description** | **Default value** | | ----------------- | ------------------------------------------------------------ | ----------------- | | `--zap-log-level` | Specify the logging level of detail for the Kubernetes Operator. The available options are `debug`, `info`, and `error`. | `debug` | --- ## Sync secrets from 1Password to AWS Secrets Manager (beta) # Sync secrets from 1Password to AWS Secrets Manager (Beta) Use the 1Password AWS Secrets Manager integration to centralize secrets management and simplify your workflow. [Create an environment with variables in 1Password](/docs/environments/), then securely sync those secrets to AWS Secrets Manager. :::tip Share your feedback To share your thoughts about the integration with us, submit your feedback using our [feedback form](https://forms.gle/3NUc7g3ywL4moksD7). ::: ## Requirements Before you can use the 1Password AWS Secrets Manager integration, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install the 1Password desktop app.](https://1password.com/downloads) 3. [Turn on 1Password Developer and create an environment](/docs/environments#turn-on-1password-developer) to use with AWS Secrets Manager. 4. Have an AWS account with the ability to create IAM resources. ## Set up the AWS Secrets Manager integration ### Step 1: Navigate to the AWS configuration page in 1Password 1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Environments**. 2. Find the name of the environment you created for AWS Secrets Manager and select **View environment**. 3. Go to the **Destinations** tab, then select **Configure destination** for AWS Secrets Manager. This opens the AWS Secrets Manager configuration page, where you can set up the integration to sync the environment from 1Password to AWS Secrets Manager. ### Step 2: Register the 1Password Secrets Sync SAML provider Authentication to your AWS account happens through SAML. You'll need to register the 1Password Secrets Sync SAML provider within your AWS account. #### 2.1: Download the SAML metadata from 1Password On the AWS Secrets Manager configuration page in 1Password, select **Download SAML metadata**. This will download a `saml-metadata.xml` file to your Downloads folder. #### 2.2 Add the SAML provider in AWS 1. [Sign in to the AWS Management Console ](https://console.aws.amazon.com/) and navigate to the [Identity and Access Management (IAM) console. ](https://console.aws.amazon.com/iam/) 2. From the navigation pane, select **Identity providers**, then select **Add provider**. 3. Configure the following provider details: - **Provider type**: Select **SAML** as the provider type, if it's not already selected. - **Provider name**: Enter the name you want to use for the identity provider. For example: `1PasswordSecretsSync`. - **Metadata document**: Select **Choose file**, then select the **`saml-metadata.xml`** file you saved to your Downloads folder in the previous step. 4. Scroll to the bottom of the page and select **Add provider**. You should see a message that says the provider was added. #### 2.3 Add the SAML provider ARN to the 1Password configuration page 1. In the [identity providers area of the IAM console ](https://console.aws.amazon.com/iam/home#/identity_providers), search the list for the provider you added. 2. Select the provider name to open its details. 3. Copy the **ARN** from the **Summary** section. 4. In the 1Password app, paste the ARN you copied from AWS into the **SAML provider ARN** field. ### Step 3: Create an IAM policy for managing secrets 1. From the navigation pane of the [AWS IAM console ](https://console.aws.amazon.com/iam/), select **Policies**, then select **Create policy**. 2. Select **JSON** as the policy editor. 3. Copy the following permission statement and paste it into the policy editor window, replacing any default content already in the editor: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:RestoreSecret", "secretsmanager:PutSecretValue", "secretsmanager:CreateSecret", "secretsmanager:DeleteSecret", "secretsmanager:TagResource", "secretsmanager:UpdateSecret" ], "Resource": "*" } ] } ``` 4. Select **Next**. 5. On the "Review and create" page, enter a name for the policy in the **Policy name** field. For example: `1PasswordSecretsSync`. You can optionally add a description in the **Description** field. 6. Scroll to the bottom of the page and select **Create policy**. You should see a message that says the policy was created. ### Step 4: Create an IAM role for the sync integration #### 4.1: Create the IAM role in AWS 1. From the navigation pane of the [AWS IAM console ](https://console.aws.amazon.com/iam/), select **Roles**, then select **Create role**. 2. From the list of trusted entity types, select **SAML 2.0 federation**. 3. Select the **SAML 2.0–based provider** menu, then select the SAML provider you created in [step 2](#22-add-the-saml-provider-in-aws). 4. Under **Access to be allowed**, select **Add programmatic access only** and configure the following fields: - **Attribute**: Select **SAML:sub** from the menu. - **Value**: Go back to the 1Password configuration page and select **Copy SAML subject**. Then paste the SAML subject in the **Value** field. 5. Scroll to the bottom of the page and select **Next**. 6. Select the checkbox next to the policy you just created, then scroll to the bottom of the page and select **Next**. Only select the checkbox and not the name of the policy itself. 7. On the "Name, review, create" page, enter a name for the IAM role in the **Role name** field. You can optionally add a description in the **Description** field. 8. Scroll to the bottom of the page and select **Create role**. You should see a message that says the policy was created. #### 4.2 Add the IAM role ARN to the 1Password configuration page 1. In the [Roles area of the IAM console ](https://console.aws.amazon.com/iam/home#/roles), search the list for the role you added. 2. Select the role name to open its details. 3. Copy the **ARN** from the **Summary** section. 4. In the 1Password app, paste the ARN you just copied from AWS into the **IAM role ARN** field. ### Step 5: Configure the target region and secret name in 1Password 1. In the 1Password app, find the **Target region** field in the configuration page. Enter the AWS Secrets Manager region where you want to sync your Environment. For example: **`us-east-1`** or **`eu-central-1`**. If you're not sure what region your account uses, [go to the AWS console ](https://console.aws.amazon.com/) and check which region is displayed in the URL. For example: `https://us-east-1.console.aws.amazon.com/console/home/`. 2. 1Password automatically populates the **Target secret name** field with the name of your environment. You can edit this field if you want to change the name of the secret, or you can edit the name of the secret in AWS later. AWS Secrets Manager does not allow duplicate names, so make sure it’s unique. 3. (Optional) If you use a custom KMS key with AWS Secrets Manager, you can enter [the key's ID or ARN ](https://docs.aws.amazon.com/kms/latest/developerguide/find-cmk-id-arn.html) in the **KMS key ID** field. AWS will then encrypt your secrets with this key. If you set a value for this field, make sure the IAM role has the [required KMS permissions. ](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html) ### Step 6: Create the AWS Secrets Manager integration in 1Password 1. Review the configuration details in 1Password. 2. When you've finished, select **Create integration** in the 1Password app. ### Step 7: Test the connection and enable the integration in 1Password You should now see a Destination card for AWS Secrets Manager. Select **Test connection** on the card to test the connection to AWS. This creates and immediately deletes a placeholder value in AWS Secrets Manager, to ensure the correct permissions have been granted for the sync integration. If everything is set up correctly and the test is successful, select the toggle to enable the integration and start syncing to AWS Secrets Manager. ### Step 8: Sync your secrets from 1Password to AWS After you enable the AWS Secrets Manager integration, any variables saved in your Environment will be synced to AWS Secrets Manager. With the secrets synced to AWS Secrets Manager, you can use one of the [methods provided by AWS ](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html) to load the secrets into your application or workload on AWS. ## How the integration works The secrets sync integration runs on 1Password's [Confidential Computing platform ](https://blog.1password.com/confidential-computing/), leveraging [AWS Nitro Enclaves ](https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave.html), to ensure a reliable, always-on sync to AWS Secrets Manager. This allows you to set up the integration once per environment, only requiring AWS credentials to create the IAM resources. After the integration is set up, you can invite team members to edit the environment in 1Password without needing to provide AWS credentials to each person. _[A diagram that illustrates how the integration works. When you change an environment secret in the 1Password desktop app, it triggers a sync to the Confidential Computing platform (AWS Nitro Enclave) which 1Password uses for syncing secrets. The change is then propagated securely from the Confidential Computing platform to the AWS Secrets Manager, then from AWS to the application running on AWS that uses the environment secret.]_ Learn more about some [limitations of the integration](#limitations). ## Manage the integration ### Update your environment secrets If you need to add, update, or remove any environment variables, [make the changes in your 1Password Environment](/docs/environments#manage-an-environment), then save your changes to trigger another sync from 1Password to AWS Secrets Manager. ### Stop using the integration You can disable the AWS Secrets Manager integration to temporarily stop syncing your environment secrets from 1Password to AWS, or delete the integration to remove it. In the 1Password desktop app, navigate to the environment you're using with AWS Secrets Manager and select the **Destinations** tab. Toggle the switch on the AWS Secrets Manager card to **Disabled** to stop syncing your environment. Or select the vertical ellipses > **Delete destination** to remove the integration. ## Troubleshooting | Error | Troubleshooting steps | | --- | --- | | The IAM role doesn't have the necessary permissions to manage secrets in AWS Secrets Manager. | Check the policy attached to your IAM role in AWS and make sure the role's IAM policy is [configured correctly](#step-3-create-an-iam-policy-for-managing-secrets). | | The sync integration failed to assume the IAM role. | Make sure that the [SAML provider is registered correctly](#step-2-register-the-1password-secrets-sync-saml-provider) and that the [IAM role](#step-4-create-an-iam-role-for-the-sync-integration) has the right [trust policy attached](#step-3-create-an-iam-policy-for-managing-secrets). | There's an outage or internal error within the AWS platform. | [Check the AWS Health Dashboard ](https://docs.aws.amazon.com/health/latest/ug/aws-health-account-views.html) for any events affecting AWS services in your account and try again later. [Contact 1Password support](mailto:support@1password.com) if the problem persists. | | The KMS key is invalid or can’t be used. | [Verify the KMS key exists in AWS ](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html) and that it has an IAM policy that allows it to be used with [AWS Secrets Manager. ](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html) | | The AWS Secrets Manager quota has been reached. | Try again later or remove resources to stay within the [AWS Secrets Manager quotas. ](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_limits.html) | | The environment exceeds the maximum size allowed in AWS Secrets Manager (64 KB). | [Create additional environments](/docs/environments#create-an-environment) so you can split the large environment into multiple smaller environments. Then set up a separate integration for each one so all your secrets are synced. | | The SAML subject isn't set correctly in the IAM role's trust policy. | [Update the IAM role’s trust policy ](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-trust-policy.html) to set the correct SAML subject as the `saml:sub` condition. | | A secret with the configured name already exists in AWS Secrets Manager. | [Set a different target secret name](#step-5-configure-the-target-region-and-secret-name-in-1password) on the configuration page in 1Password, or [delete the secret ](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_delete-secret.html) in AWS Secrets Manager that uses the same name. | If you encounter problems that you can't resolve with these steps, try [deleting the integration](#stop-using-the-integration) and setting it up again. Or [contact 1Password support](mailto:support@1password.com) for more help. ## Limitations There are some limitations to consider if you use the beta integration. - The integration supports unidirectional (one-way) syncing from 1Password to AWS Secrets Manager. Changes made to environment secrets in AWS Secrets Manager won't be synced to 1Password. - If you have environment secrets in AWS Secrets Manager that require auto-rotation, you should continue to manage them there. This will prevent environment secrets becoming out of sync between AWS and 1Password. - It's best practice to maintain one definitive copy of a secret in 1Password, either as a 1Password item or as a variable in a 1Password environment. Keeping multiple copies of the same secret could lead to different versions becoming out of sync. - There's a 64KB size limit for environments synced to AWS Secrets Manager. An example of where you might run into this limit is if you're defining environment variables for a monolithic application. In this scenario, you could split variables out into separate environments, each with it's own sync integration. ## Learn more - [1Password Environments](/docs/environments) - [Access secrets from 1Password through local `.env` files](/docs/environments/local-env-file) - [Get started with 1Password Developer ](https://support.1password.com/developer/) --- ## Validate local .env files from 1Password Environments with Cursor Agent You can use the [1Password Cursor hook ](https://cursor.com/marketplace/1password) to validate that [locally mounted `.env` files from 1Password Environments](/docs/environments/local-env-file/) are properly set up before [Cursor Agent ](https://cursor.com/docs/agent/overview) executes shell commands. If any required `.env` files are missing or invalid, the hook prevents Cursor from running the command and provides instructions for how to fix the issue. ## Requirements - [1Password subscription](https://1password.com/pricing/password-manager) - 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux) - [Cursor ](https://cursor.com/home) - [`sqlite3` ](https://sqlite.org/index.html) installed and available in your PATH :::note Windows not supported Local `.env` files for 1Password Environments are currently only supported on Mac and Linux. If you're on Windows, the hook will skip the validation checks. ::: ## Step 1: Set up your Environments To use the 1Password hook, you'll first need to: 1. [Create one or more Environments](/docs/environments) in 1Password to store your project secrets. 2. [Configure locally mounted `.env` files](/docs/environments/local-env-file) for them. ## Step 2: Install the hook in your project The 1Password Cursor hook is available as a plugin in the Cursor marketplace. To install it: 1. Open the [Cursor marketplace ](https://cursor.com/marketplace/1password). 2. Either select **Sign In To Add** (or **Add** if you're already signed in), or copy `/add-plugin 1password` from the marketplace page and run it in Cursor Agent window to install the 1Password plugin. After you install the plugin, restart Cursor and tell the Cursor Agent to perform a task that requires running a shell command. If your `.env` files are properly configured, the command will proceed. Otherwise the Agent will guide you through fixing the issue. To confirm the hook worked as expected, open Cursor, then navigate to **Settings** > **Hooks** > **Execution Log**. You can also install the hook from the [1Password Cursor Hooks repository ](https://github.com/1Password/cursor-hooks/blob/main/.cursor/hooks/1password/README.md). ## Step 3: Choose how you want the hook to validate your `.env` files ### Default mode By default, the hook will check the 1Password desktop app to find `.env` files related to your project based on the file path destinations you configured in 1Password Environments. ### Configured mode Alternatively, you can create a `.1password/environments.toml` file at the root of your project that specifies which locally mounted `.env` files to validate. The hook only validates the specified files. To do this, the hook parses the TOML file to extract mount paths from the `mount_paths` array field. Mount paths can be relative to the project root or absolute. For example: ```toml title=".1password/environments.toml" mount_paths = ["application.env", "billing.env"] ``` The `mount_paths` field must be explicitly defined in the TOML file. If the file exists but doesn't contain a `mount_paths` field, the hook will log a warning and fall back to default mode. If no `.env` files are specified in the TOML file, all commands will be allowed to run. ## How it works [Cursor hooks ](https://cursor.com/docs/agent/hooks) are custom scripts that run before or after specific stages of the agent loop. Each hook runs as a spawned process that communicates with Cursor over standard input and output using JSON in both directions. Hooks can observe, block, or modify the agent’s behavior as it runs. The 1Password hook is designed to be used with the [`beforeShellExecution` event ](https://cursor.com/docs/agent/hooks#hook-events), so that the hook is called before any shell command is executed by the agent. The hook returns a permission decision that decides whether or not the command is allowed to run. When Cursor Agent tries to execute a command, the hook first checks for a `.1password/environments.toml` file in the current project directory. If a TOML file exists and contains the required `mount_paths` field, Cursor validates only the specified `.env` files. If no TOML file exists, Cursor queries the 1Password desktop app for all `.env` files mounted in the project directory. The hook then confirms that each `.env` file discovered for the project is enabled, the mount file exists, and the file is a valid FIFO (named pipe). If all required `.env` files are enabled and configured correctly, the command is allowed to proceed. If one or more required `.env` files are missing, disabled, or invalid, the hook denies shell execution and provides an error message with steps to fix the issue. The hook uses a "fail open" approach in default mode. If it can't access the 1Password database, the hook logs a warning and allows subsequent commands to proceed. This makes sure development can proceed if the 1Password app is not installed or the database is unavailable. Similarly, if a TOML file exists but no `.env` files are specified, the command is allowed to proceed. ### Configuration examples Single .env file ```toml title=".1password/environments.toml" mount_paths = [".env"] ``` Only `.env` is validated. Other environment files are ignored. Multiple `.env` files ```toml title=".1password/environments.toml" mount_paths = [".env", "billing.env", "database.env"] ``` Only the three declared `.env` files are validated. No validation ```toml title=".1password/environments.toml" mount_paths = [] ``` No `.env` files are validated. All commands are allowed. Default mode No `.1password/environments.toml` file exists or the `mount_paths` field has been improperly defined. The hook discovers and validates all mounts configured in 1Password that are within the project directory. ## Troubleshooting The hook logs information to `/tmp/1password-cursor-hooks.log` for troubleshooting. Check this file if you encounter issues. Log entries include timestamps and detailed information about: - Database queries and results - Mount validation checks - Permission decisions - Error conditions To enable debug mode, set `DEBUG=1` to output logs directly to the shell instead of the log file: ```shell DEBUG=1 echo '{ "command": "echo test" }' | ./.cursor/hooks/1password/validate-mounted-env-files.sh ``` ## Learn more - [1Password plugin in the Cursor marketplace ](https://cursor.com/marketplace/1password) - [1Password Cursor Hooks repository ](https://github.com/1Password/cursor-hooks/blob/main/.cursor/hooks/1password/README.md) - [Cursor Hooks ](https://cursor.com/docs/agent/hooks) - [Access secrets from 1Password through local `.env` files](/docs/environments/local-env-file) --- ## Access secrets from 1Password through local `.env` files (beta) # Access secrets from 1Password through local `.env` files (Beta) Locally mounted `.env` files allow secure access to the secrets you've stored in [1Password Environments](/docs/environments) from your device, without needing to keep them in a plaintext `.env` file on your local device. By creating a local `.env` file [destination](/docs/environments#destinations), your secrets become both safe and simple to access. ## Mount your `.env` file To configure a local `.env` file destination, you'll need to use the 1Password desktop app to create a new [Environment](/docs/environments#create-an-environment) or navigate to an existing one to configure the destination for. Within your Environment: 1. Select the **Destinations** tab, then select **Configure destination** for a "Local `.env` file". 2. Select **Choose file path** and choose the path on your device where you want to create your local `.env` file. 3. Select **Mount .env file**. You can disable a local `.env` file to remove it from your device. In the Destinations tab of your Environment, toggle the **Enabled** option on or off as needed. You can have up to ten enabled local `.env` files per device. :::important Note If you have an existing `.env` file tracked by Git at the path you want to mount a new `.env` file at, you'll first need to delete the existing file and commit the change. After this is done you can safely mount your new `.env` file at the desired path. If you don’t delete and commit the existing file, Git operations may fail and indicate that the mounted `.env` file generated by 1Password is being tracked. In practice, the file can’t actually be committed and its contents will never enter the staging area, so your secrets remain safe. However, commands like `git status` may still show it as a change until you’ve committed the removal of the original file. ::: ## Verify with your terminal To confirm that you can access your environment variables on your device, you can read your secrets using the `cat` shell command. 1. From your terminal, navigate to the directory where your `.env` file is saved. Run the following command, replacing .env with the name you've given your file: ```shell [{"color": "bitsblue", "lineNo": 1, "substr": ".env"}] cat .env ``` 2. Select **Authorize** in the authorization prompt that pops up. Upon approval, your Environment's contents will be returned. Your terminal only reads your environment variables one time, and doesn't write them to disk. Authorization lasts until 1Password locks so you won't have to re-approve additional read requests while 1Password remains unlocked. ### Dotenv library compatibility You can use your language's supported `.env` libraries to load secrets into your projects and work with your environment variables. Use of local `.env` files with 1Password Environments is compatible with the following libraries: | Language / Tool | Library | Compatible | | --- | --- | --- | | C# | [`DotNetEnv` ](https://github.com/tonerdo/dotnet-env) | ✅ Yes | | Docker Compose | [Built-in support for `.env` files ](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/) | ✅ Yes | | Go | [`godotenv` ](https://github.com/joho/godotenv) | ✅ Yes | | Java | [`dotenv-java` ](https://github.com/cdimascio/dotenv-java) | ✅ Yes | | JavaScript / Node.js | [`dotenv` ](https://github.com/motdotla/dotenv) | ✅ Yes | | PHP | [`phpdotenv` ](https://github.com/vlucas/phpdotenv) | ✅ Yes | | Python | [`python-dotenv` ](https://github.com/theskumar/python-dotenv) | ✅ Yes, as of `v1.2.1` | | Ruby | [`dotenv` ](https://github.com/bkeepers/dotenv) | ✅ Yes | | Rust | [`dotenvy` (main) ](https://github.com/allan2/dotenvy) | ✅ Yes | | Rust | [`dotenvy` (v0.15.7) ](https://github.com/allan2/dotenvy/tree/v0.15.7) | ⚠️ Yes, but requires that you pass in the `.env` filename, path, or contents directly. | ## How it works 1Password makes your environment variables available as a `.env` file without actually storing the plaintext contents on your device. Instead, the file contents are passed directly to the reader process on demand through a UNIX-named pipe. 1Password mounts the `.env` file at the path you've specified on your device and automatically remounts it whenever 1Password restarts. This means that as long as 1Password is running, even if locked, the file is there and 1Password is ready to respond when you need to access your secrets. When your application tries to read the file, you'll receive an authorization prompt asking for approval to populate the `.env` file. The file will lock again [when 1Password locks](https://support.1password.com/auto-lock/). There's no distinction made between different processes reading the file. Once the file is unlocked, every process can read it until you lock 1Password or disable the `.env` file in 1Password. Although 1Password creates this file on your device, locally mounted `.env` files aren't tracked by Git and therefore your secrets aren't exposed by your version control system. The contents of these files are never stored on disk and are only available at the moment you access them, provided you've authenticated. Once read, the information is no longer available until you access it again. _[An authorization prompt is shown when you try to access a mounted `.env` file through your local terminal.]_ ## Limitations - Local `.env` file destinations are only supported in 1Password for Mac and Linux at this time. - Local `.env` file destinations aren't designed for concurrent access. If multiple processes try to read your local `.env` file at the same time, you may encounter delays or unexpected behaviors. For example, if you have the file open in an IDE while another application attempts to read it, this may result in conflicts. The first process to access the file will succeed in reading the secrets, while others may fail to read the contents. If you have the `.env` file open in an IDE or another application that is actively accessing it, you may need to close that session to allow other applications or terminal instances to read the file without interference. - When you're offline, you'll only be able to access the most recent contents synced to your device or local changes you've made. When you're back online, your Environment will update to reflect the latest changes you've saved in 1Password. ## Learn more - [1Password Environments (beta)](/docs/environments) - [Use Cursor hooks to validate 1Password environment mounts](/docs/environments/cursor-hook-validate) - [Sync secrets between 1Password and AWS Secrets Manager (beta)](/docs/environments/aws-secrets-manager) - [Get started with 1Password Developer](https://support.1password.com/developer) --- ## 1Password Environments (beta) # 1Password Environments (Beta) 1Password Environments allow you to organize and manage your project's environment variables, separately from the rest of the items in your 1Password vaults. You can create an Environment for each project or development stage, then securely access your variables directly from 1Password when you need them. With Environments, you can: - Make your Environment's variables available via [locally mounted `.env` files](/docs/environments/local-env-file), without writing your credentials to disk. - Validate your locally mounted `.env` file setup with [Cursor Agent](/docs/environments/cursor-hook-validate). - Programatically [read your environment variables](/docs/environments/read-environment-variables) from 1Password in your terminal or in your Go, JavaScript, or Python integrations. - Securely sync your environment variables to [AWS Secrets Manager](/docs/environments/aws-secrets-manager). - [Share Environments with your team members](#share-an-environment) for easier collaboration and onboarding. You can import your project variables to Environments from your existing `.env` files, or by manually adding key-value pairs for each variable. _[A 1Password Environment with several environment variables added to it.]_ :::caution When sharing an Environment with others and reading its contents outside of 1Password, review the Environment's values carefully before using them in any program or workflow. What you store in 1Password is exactly what we provide when you read your Environment. ::: ## Requirements Before you can use Environments, you'll need to: - [Sign up for 1Password](https://1password.com/pricing/password-manager). - Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). This feature is not available in 1Password for iOS or Android. - Have [1Password Developer turned on](#turn-on-1password-developer). ### Turn on 1Password Developer 1. Open and unlock the 1Password desktop app. 2. Select your account or collection at the top of the sidebar, then select **Settings** > [**Developer**](onepassword://settings/developers). 3. Turn on **Show 1Password Developer experience**. ## Create an Environment 1. In the 1Password desktop app, go to **Developer** > **View Environments**. 1. Select **New environment**. 1. Enter a name for the new environment, then select **Save**. If you have multiple 1Password accounts, you can select which account to save the Environment to. ## Add variables to an Environment After you create an Environment, you can add your project secrets as variables. 1Password Environment variables map to conventional [environment variables ](https://en.wikipedia.org/wiki/Environment_variable). Each variable is a key-value pair that includes a name (for example, `DB_HOST`, `DB_USER`, or `API_KEY`) and a value that holds the corresponding secret. To add variables to an Environment, open and unlock the 1Password desktop app, navigate to **Developer** > **View Environments**, then select the Environment you want to update. You can add variables in two ways: - If you have an existing `.env` file for your project, select **Import .env file**. 1Password will automatically import your environment variables. - To manually add environment variables, select **New variable**. Enter the environment variable name in the **Name** field and its secret in the **Value** field. Repeat this process for each environment variable you want to add. :::note Values are hidden by default, which means they'll be masked in the output of CLI and SDK operations. To change this, select the verticle ellipsis next to the variable, then select **Show value by default**. ::: You can add, edit, or remove variables from your Environment at any time. To update your variables, open the Environment and select **Edit**. ## Use your Environments in your workflows In the 1Password desktop app, each Environment has a tab called Destinations where you can configure your Environment to use in your workflows. The following destinations are available: - [**Local `.env` file**](/docs/environments/local-env-file): Create a locally mounted `.env` file to make your environment variables available during local development without writing plaintext secrets to disk. - [**Cursor Agent**](/docs/environments/cursor-hook-validate): Use 1Password's Cursor Hook to validate your locally mounted `.env` files before Cursor Agent executes shell commands. - [**Programatically read Environments**](/docs/environments/read-environment-variables): Read environments then pass environment variables to applications and scripts using 1Password CLI or 1Password SDKs. - [**AWS Secrets Manager**](/docs/environments/aws-secrets-manager): Sync secrets from 1Password to AWS Secrets Manager. ## Manage your Environments :::tip 1Password Environments return values exactly as they are entered. Format your values as you would in a standard `.env` file. For example: - If a value contains a space, enclose the value in quotation marks: `"bar baz"` - If a value contains special characters, escape them with a `\`: `\$100` ::: Values are hidden by default, but you can toggle the visibility on or off in the **Actions** column. You can also delete variables from this column. Select **Edit** within the environment to add, edit, or delete variables at a later time. ### Rename or remove an Environment If you want to rename or remove an Environment: 1. In the 1Password desktop app, go to **Developer** > **View Environments**. 2. Select the Environment you want to manage, then select **Manage Environment**. 3. Choose **Rename environment** or **Delete environment**. :::caution Deleted Environments cannot be restored and any associated integrations will stop working. 1Password will prompt you to confirm whether or not you want to delete your Environment before proceeding. ::: ### Share an Environment If you're using a shared account, such as for a team or business, you can share Environments with your team members. Each Environment remains independent, allowing you to work across multiple environments in different accounts while keeping environment variables separate. Access must be granted for each Environment. To share an Environment: 1. In the 1Password desktop app, go to **Developer** > **View Environments**. 2. Select the Environment you want to share, then select **Manage environment** > **Manage access**. 3. Select **Add People**, then search for and select the team member you want to add to the Environment. Select **Next**. 4. Select **View & Edit**, and choose whether the person can view, edit, or manage the Environment. To remove a team member from an Environment, return to the "Manage access" screen and select **Remove from environment** next to the person's name. ## Learn more - [Access secrets from 1Password through local `.env` files](/docs/environments/local-env-file) - [Validate local `.env` files from 1Password Environments with Cursor Agent](/docs/environments/cursor-hook-validate) - [Sync secrets between 1Password and AWS Secrets Manager (beta)](/docs/environments/aws-secrets-manager) - [Programatically read Environments with 1Password CLI or 1Password SDKs](/docs/environments/read-environment-variables) --- ## Programatically read 1Password Environments # Programatically read 1Password Environments (Beta) You can programatically retrieve environment variables from [1Password Environments](/docs/environments) using [1Password SDKs](#sdks) or [1Password CLI](#cli). Both tools support local authentication with the 1Password desktop app or automated authentication with service accounts scoped to specific Environments. ## Choose your configuration ### Tool options - **1Password CLI**: Best for quick testing, shell scripts, CI/CD pipelines, Infrastructure as Code, build tools and task runners. - **1Password SDKs**: Best for native integrations with Go, Python, or JavaScript applications. ### Authentication options - **Local authentication with the 1Password desktop app**: Authenticate in the same way you unlock your [1Password desktop app](https://1password.com/downloads/), like with biometrics or your 1Password account password. Requires minimal setup with no token management. Enables human-in-the-loop approval for sensitive workflows. - **1Password Service Accounts**: Authenticate using a [service account token](/docs/service-accounts/) scoped to the Environments you want to fetch. Best for shared building, automated access, and headless server authentication. Enables you to follow the [principle of least privilege ](https://csrc.nist.gov/glossary/term/least_privilege) in your project. ### Decision guide Use the table below to find the best tool and authentication method for your specific use case. | Use case | Recommended tool | Authentication method | Why this approach | | --- | --- | --- | --- | | **Local development** on your machine | [CLI](#cli) or [SDK](#sdks) | Desktop app | Uses existing 1Password account credentials, making it seamless for individual developers working locally. No token management. | | **Quick testing** and exploration | [CLI](#cli) | Desktop app | Fastest way to test. Uses existing 1Password account credentials with minimal setup required. | | **Desktop applications** | [SDK](#sdks) | Desktop app | Better integration with application code. Desktop app authentication allows end users to authenticate with their own 1Password accounts. | | **Shell scripts** and automation tasks | [CLI](#cli) | Desktop app or service account | 1Password CLI is designed for shell scripting. Use 1Password desktop app for personal scripts, service accounts for shared/automated scripts. | | **CI/CD pipelines** (GitHub Actions, GitLab CI, etc.) | [CLI](#cli) | Service account | Service accounts provide non-interactive authentication perfect for automated workflows. 1Password CLI is lightweight and easy to integrate into pipeline scripts. | | **Application runtime** (production services) | [SDK](#sdks) | Service account | 1Password SDKs offer native language integration with better error handling and type safety. Service accounts enable secure, automated access without user interaction. | | **Server-side applications** | [SDK](#sdks) | Service account | 1Password SDKs offer robust error handling and connection pooling. Service accounts enable headless server authentication. | | **Docker containers and Kubernetes** | [SDK](#sdks) or [CLI](#cli) | Service account | Service accounts work well in containerized environments. Choose 1Password SDKs for application containers, 1Password CLI for init containers or sidecars. | | **Infrastructure as Code** (Terraform, Pulumi, etc.) | [CLI](#cli) | Service account | 1Password CLI can be easily invoked from IaC tools. Service accounts enable automated infrastructure provisioning. | | **Build tools and task runners** | [CLI](#cli) | Desktop app or service account | 1Password CLI integrates easily with build tools like Make, Gradle, or npm scripts. Use 1Password desktop app for developer builds. Service accounts support shared building. | ## Get an Environment's ID To fetch environment variables from a 1Password Environment, you'll need its unique identifier (ID). You can get an Environment's ID in the [1Password desktop app](https://1password.com/downloads/): 1. Open and unlock the 1Password desktop app, then navigate to **Developer** > **View Environments**. 2. Select **View environment** next to the Environment you want to fetch. 3. Select **Manage environment** > **Copy environment ID**. ## Read Environments with 1Password SDKs {#sdks} ### Before you get started To use this feature, you'll need to install the beta version of the Go, JS, or Python SDK: **Go:** ```shell go get github.com/1password/onepassword-sdk-go@v0.4.1-beta.1 ``` **JavaScript:** ```shell npm install @1password/sdk@0.4.1-beta.1 ``` **Python:** ```python pip install onepassword-sdk==0.4.1b1 ``` Then [follow the steps](/docs/sdks#get-started) to set up your project to authenticate with your 1Password desktop app or a service account token. ### Get environment variables With [1Password SDKs](/docs/sdks), you can retrieve environment variables from your 1Password Environments using the `get_variables()` function with the [Environment's ID](#get-an-environments-id). **Go:** ```go func (e *EnvironmentsSource) GetVariables(ctx context.Context, environmentID string) (*GetVariablesResponse, error) ``` **JavaScript:** ```js async getVariables(environmentId: string): Promise<GetVariablesResponse> ``` **Python:** ```python async def get_variables(self, environment_id: str) -> GetVariablesResponse ``` The function returns a `GetVariablesResponse` object that contains a list of the environment variables stored in the Environment. **Go:** ```go type GetVariablesResponse struct { Variables []EnvironmentVariable `json:"variables"` } ``` **JavaScript:** ```js interface GetVariablesResponse { variables: EnvironmentVariable[]; } ``` **Python:** ```python class GetVariablesResponse(BaseModel): variables: List[EnvironmentVariable] ``` Each environment variable in the response contains the environment variable's name (for example, `DB_HOST`), value, and whether the value is hidden by default. **Go:** ```go type EnvironmentVariable struct { Name string `json:"name"` Value string `json:"value"` Masked bool `json:"masked"` } ``` **JavaScript:** ```js interface EnvironmentVariable { name: string; value: string; masked: boolean; } ``` **Python:** ```python class EnvironmentVariable(BaseModel): name: str value: str masked: bool ``` :::note By default, 1Password Environment variables have **"Hide value by default"** turned on. To change this, open an Environment, select the verticle ellipsis next to the variable, then select **Show value by default**. ::: #### Examples **Go:** **Service account:** Before running the following example: - Set `OP_SERVICE_ACCOUNT_TOKEN` to the token for a service account that has access to the Environment you want to fetch. - Set `OP_ENVIRONMENT_ID` to the ID for your 1Password Environment. ```go package main "context" "fmt" "os" "github.com/1password/onepassword-sdk-go" ) func main() { ctx := context.Background() // Initialize the SDK client client, err := onepassword.NewClient( ctx, onepassword.WithServiceAccountToken(os.Getenv("OP_SERVICE_ACCOUNT_TOKEN")), onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), ) if err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) } // Get all variables from the environment environmentID := os.Getenv("OP_ENVIRONMENT_ID") response, err := client.Environments().GetVariables(ctx, environmentID) if err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) } // Process the variables for _, v := range response.Variables { visibility := "visible" if v.Masked { visibility = "hidden" } fmt.Printf("%s=%s (%s by default)\n", v.Name, v.Value, visibility) } } ``` **1Password desktop app:** Before running the following example: - Replace `YourAccountName` in the code blow with your 1Password account name as it appears at the top left sidebar in the 1Password desktop app. - Set `OP_ENVIRONMENT_ID` to the ID for your 1Password Environment. ```go package main "context" "fmt" "os" "github.com/1password/onepassword-sdk-go" ) func main() { ctx := context.Background() // Initialize the SDK client client, err := onepassword.NewClient( ctx, onepassword.WithDesktopAppIntegration(os.Getenv("OP_ACCOUNT_NAME")), onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), ) if err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) } // Get all variables from the environment environmentID := os.Getenv("OP_ENVIRONMENT_ID") response, err := client.Environments().GetVariables(ctx, environmentID) if err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) } // Process the variables for _, v := range response.Variables { visibility := "visible" if v.Masked { visibility = "hidden" } fmt.Printf("%s=%s (%s by default)\n", v.Name, v.Value, visibility) } } ``` **JavaScript:** **Service account:** Before running the following example: - Set `OP_SERVICE_ACCOUNT_TOKEN` to the token for a service account that has access to the Environment you want to fetch. - Set `OP_ENVIRONMENT_ID` to the ID for your 1Password Environment. ```js const client = await createClient({ auth: process.env.OP_SERVICE_ACCOUNT_TOKEN, integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); // Get all variables from the Environment const environmentId = process.env.OP_ENVIRONMENT_ID; const response = await client.environments.getVariables(environmentId); // Process the variables response.variables.forEach(({ name, value, masked }) => { const visibility = masked ? "hidden" : "visible"; console.log(`${name}=${value} (${visibility} by default)`); }); ``` **1Password desktop app:** Before running the following example: - Replace `YourAccountName` in the code blow with your 1Password account name as it appears at the top left sidebar in the 1Password desktop app. - Set `OP_ENVIRONMENT_ID` to the ID for your 1Password Environment. ```js const client = await createClient({ auth: new DesktopAuth(process.env.OP_ACCOUNT_NAME), integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); // Get all variables from the Environment const environmentId = process.env.OP_ENVIRONMENT_ID; const response = await client.environments.getVariables(environmentId); // Process the variables response.variables.forEach(({ name, value, masked }) => { const visibility = masked ? "hidden" : "visible"; console.log(`${name}=${value} (${visibility} by default)`); }); ``` **Python:** **Service account:** Before running the following example: - Set `OP_SERVICE_ACCOUNT_TOKEN` to the token for a service account that has access to the Environment you want to fetch. - Set `OP_ENVIRONMENT_ID` to the ID for your 1Password Environment. ```python from onepassword import Client async def main(): # Initialize and authenticate the client client = await Client.authenticate( auth=os.environ.get("OP_SERVICE_ACCOUNT_TOKEN"), integration_name="My 1Password Integration", integration_version="v1.0.0", ) # Get all variables from the Environment environment_id = os.environ.get("OP_ENVIRONMENT_ID") response = await client.environments.get_variables(environment_id) # Process the variables for var in response.variables: visibility = "hidden" if var.masked else "visible" print(f"{var.name}={var.value} ({visibility} by default)") asyncio.run(main()) ``` **1Password desktop app:** Before running the following example: - Replace `YourAccountName` in the code blow with your 1Password account name as it appears at the top left sidebar in the 1Password desktop app. - Set `OP_ENVIRONMENT_ID` to the ID for your 1Password Environment. ```python from onepassword import Client, DesktopAuth async def main(): # Initialize and authenticate the client client = await Client.authenticate( auth=DesktopAuth(os.environ.get("OP_ACCOUNT_NAME")), integration_name="My 1Password Integration", integration_version="v1.0.0", ) # Get all variables from the Environment environment_id = os.environ.get("OP_ENVIRONMENT_ID") response = await client.environments.get_variables(environment_id) # Process the variables for var in response.variables: visibility = "hidden" if var.masked else "visible" print(f"{var.name}={var.value} ({visibility} by default)") asyncio.run(main()) ``` ## Read Environments with 1Password CLI {#cli} With [1Password CLI](/docs/cli), you can retrieve environment variables from your 1Password Environments with `op environment read` and pass them to an application or script using `op run --environment`. ### Before you get started Before you get started, install the [latest beta build of 1Password CLI](/docs/cli/reference#beta-builds), version `2.33.0-beta.02` or later. Then choose your authentication method: - **Local authentication with the 1Password desktop app**: Authenticate in the same way you unlock your [1Password desktop app](https://1password.com/downloads/), like with biometrics or your 1Password account password. To set up local authentication, [turn on the 1Password CLI desktop app integration](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). - **Service account**: Authenticate using a service account token that can only access the Environments you want to fetch. To authenticate using a service account token, [create a new service account](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/) with read access to the appropriate Environments. Then export your service account token: **bash, sh, zsh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token> ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN <your-service-account-token> ``` **Powershell:** ```shell $Env:OP_SERVICE_ACCOUNT_TOKEN = "<your-service-account-token>" ``` ### Get environment variables To read environment variables from a 1Password Environment, use `op environment read` with the [Environment's ID](#get-an-environments-id). 1Password CLI will return a list of environment variables for the Environment formatted as key-value pairs. ```shell op environment read <environmentID> ``` #### Examples To get the environment variables for a local development Environment with the ID `blgexucrwfr2dtsxe2q4uu7dp4`: ```shell op environment read blgexucrwfr2dtsxe2q4uu7dp4 #code-result DB_HOST=localhost DB_USER=admin API_KEY=sk-abc123 ``` After you fetch the Environment, you can pipe the results to other tools. For example: ```shell op environment read blgexucrwfr2dtsxe2q4uu7dp4 | grep DB_ ``` ### Pass environment variables to an application or script To pass environment variables from a 1Password Environment to an application or script, use [`op run`](/docs/cli/reference/commands/run) with the `--environment` flag and the [Environment's ID](#get-an-environments-id), then pass the results to the application or script. 1Password CLI runs the application or script as a subprocess with your secrets loaded into the environment for the duration of the process. ```shell op run --environment <environmentID> -- <command> ``` :::note By default, 1Password Environment variables have **"Hide value by default"** turned on. Hidden variables are automatically concealed in stdout and stderr output. To change this, open an Environment, select the verticle ellipsis next to the variable, then select **Show value by default**. Or use the `--no-masking` flag with `op run`. ::: #### Use with environment variables from multiple sources You can also use `op run` with multiple environments, or in combination with `.env` files or shell environment variables. When the same environment variable exists in multiple sources, 1Password CLI gives them the following precedence: 1. 1Password Environments (highest priority) 2. Environment files 3. Shell environment variables (lowest priorities) If the same variable exists in multiple 1Password Environments, the last Environment specified takes precedence. #### Examples To run the `printenv` command with the environment variables from a 1Password Environment loaded into the environment: ```shell op run --environment blgexucrwfr2dtsxe2q4uu7dp4 -- printenv #code-result DB_HOST=localhost DB_USER=admin API_KEY=sk-abc123 ``` To run a script provisioned with the environment variables from an Environment: ```shell op run --environment blgexucrwfr2dtsxe2q4uu7dp4 -- ./my-script.sh ``` ## Learn more - [Access secrets from 1Password through local .env files](/docs/environments/local-env-file) - [Validate local .env files from 1Password Environments with Cursor Agent](/docs/environments/cursor-hook-validate) - [Sync secrets from 1Password to AWS Secrets Manager](/docs/environments/aws-secrets-manager) --- ## Audit events You can use the [1Password Events API](/docs/events-api/reference/) to return audit events from the [audit log](https://support.1password.com/activity-log/) of your 1Password Business account and send them to your security information and event management (SIEM) system. Audit event data includes actions performed by team members in a 1Password account, such as changes made to the account, vaults, groups, users, and more. ## Read an event object When you use the 1Password Events API to fetch audit events from your 1Password Business account, the API will return a JSON array of [audit event objects](/docs/events-api/reference#post-apiv2auditevents). Event objects can include the following properties: - **`uuid`**: The unique identifier for the event. - **`timestamp`**: When the action was performed. - **`actor_uuid`**: The unique identifier for the team member who performed the action. - **`actor_details`**: The details of the team member who performed the action (including their UUID, name, and email address). - **`action`**: The type of action that was performed. - **`object_type`**: The type of object that the action was performed on. - **`object_uuid`**: The unique identifier for the object the action was performed on. - **`object_details`**: The details of the team member who is the object of the action (including their UUID, name, and email address). This property is only returned for events where the object of the action is a team member. - **`aux_id`**: The identifier that relates to additional information about the activity. - **`aux_uuid`**: The unique identifier that relates to additional information about the activity. - **`aux_details`**: The details of the team member who relates to the additional information about the activity (including their UUID, name, and email address). This property is only returned for events where the additional information about an activity relates to a team member. - **`aux_info`**: Additional information about the activity. - **`session`**: The information about the session, including the date and time the client signed in and started the session, the unique identifier of the device that signed into the session, and the IP address used. - **`location`**: The geolocation information of the client based on their IP address at the time the event was performed. To understand the activity an audit event object is describing, look at the `action`, `actor`, and `object` fields, as well as any `aux` fields that may be included. For example: ```json title="Example audit event object" [{ "badge": 1, "color": "tangerine", "lineNo": 5, "substr": "\\"actor_details\\": {" }, { "badge": 2, "color": "lagoon", "lineNo": 10, "substr": "\\"action\\": \\"join\\"," }, { "badge": 3, "color": "bitsblue", "lineNo": 11, "substr": "\\"object_type\\": \\"gm\\"," }, { "badge": 4, "color": "dahlia", "lineNo": 12, "substr": "\\"object_uuid\\": \\"pf8soyakgngrphytsyjed4ae3u\\"," }, { "badge": 5, "color": "sunbeam", "lineNo": 15, "substr": "\\"aux_details\\": {" }, { "badge": 6, "color": "intrepidblue", "lineNo": 20, "substr": "\\"aux_info\\": \\"A\\","}] { "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E", "timestamp": "2023-03-15T16:33:50-03:00", "actor_uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V", "actor_details": { "uuid:": "4HCGRGYCTRQFBMGVEGTABYDU2V", "name": "Jeff Shiner", "email": "jeff_shiner@agilebits.com" }, "action": "join", "object_type": "gm", "object_uuid": "pf8soyakgngrphytsyjed4ae3u", "aux_id": 9277034, "aux_uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY", "aux_details": { "uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY", "name": "Wendy Appleseed", "email": "wendy_appleseed@agilebits.com" }, "aux_info": "A", "session": { "uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM", "login_time": "2023-03-15T16:33:50-03:00", "device_uuid": "lc5fqgbrcm4plajd8mwncv2b3u", "ip": "192.0.2.254" }, "location": { "country": "Canada", "region": "Ontario", "city": "Toronto", "latitude": 43.5991, "longitude": -79.4988 } } ``` This example event shows that Jeff Shiner is the actor who performed the "join" action on a [group membership](#group-membership) (Jeff added someone to a group). And Wendy Appleseed is the team member who joined (was added to) the Administrator group as a [group manager](#group-membership). To get more information about an object, such as the name of a group, you can check the description of the event in the [audit log](https://support.1password.com/activity-log/), or use the object UUID to [retrieve information about an object with 1Password CLI](/docs/cli/reference#unique-identifiers-ids). Use the audit event tables below to learn more about what the different actions and objects mean and what output is returned for each type of event. A complete list of actions and objects can be found in the [appendix](#appendix). ## Audit events - [Accounts](#accounts) - [Delegate sessions](#delegate-sessions) - [Devices](#devices) - [Email changes](#email-changes) - [Family accounts](#family-accounts) - [Files](#files) - [Firewall rules](#firewall-rules) - [Groups](#groups) - [Group membership](#group-membership) - [Group vault access](#group-vault-access) - [Invites](#invites) - [Items](#items) - [Item sharing](#item-sharing) - [Managed companies](#managed-companies) - [Multi-factor authentication](#multi-factor-authentication) - [Packages](#packages) - [Provisioning](#provisioning) - [Reports](#reports) - [Service accounts](#service-accounts) - [Service account tokens](#service-account-tokens) - [Sign-in tokens](#sign-in-tokens) - [Slack app](#slack-app) - [SSO settings](#sso-settings) - [Stripe cards](#stripe-cards) - [Stripe payment methods](#stripe-payment-methods) - [Stripe subscriptions](#stripe-subscriptions) - [Templates](#templates) - [Unknown](#unknown) - [Users](#users) - [User vault access](#user-vault-access) - [User WebAuthn credentials (passkeys)](#passkeys) - [Vaults](#vaults) - [Verified domain](#verified-domain) ### Accounts Actions related to updating and confirming accounts. Event Description Action Object Type Aux Info Activate Account The account was activated. `activate` `account` Update Account Account attributes, such as the name, were changed. `update` `account` Delete Account The account was deleted. `delete` `account` Update Account Domain The account domain was changed. `update` `account` domain Change Account Type The account type was changed. `convert` `account` old account type, new account type <section> `I`: Individual account `F`: Family account `B`: Business account </section> Enable Duo Duo was enabled for the account. `enblduo` `account` Update Duo Configuration The Duo configuration for the account was updated. `updatduo` `account` Disable Duo Duo was disabled for the account. `disblduo` `account` ### Delegate sessions Actions related to delegating sessions. Event Description Action Object type Aux info Delegate Session A new delegated session was added. `dlgsess` `dlgdsess` session UUID ### Devices Actions related to authorizing and removing devices. Event Description Action Object Type Aux Info Add Device A device was added to the account. `create` `device` user ID, user UUID, user name, user email Update Device A device was updated. `update` `device` user ID, user UUID, user name, user email Delete Device A device was deleted. `delete` `device` user ID, user UUID, user name, user email Delete Old Devices Old devices were deleted. `deolddev` `user` Delete All Devices All devices were deleted. `dealldev` `user` Reauthorize Device A device was reauthorized after being deauthorized `reauth` `device` user ID, user UUID, user name, user email ### Email changes Actions related to beginning and completing email changes for team members. Event Description Action Object Type Aux Info Begin Email Change An email change was requested by a user. `begin` `ec` Complete Email Change A user's email was changed. `complete` `ec` Propose Email Change An email change was proposed by an admin. `propose` `ec` ### Family accounts Actions related to linking and unlinking family accounts. Event Description Action Object Type Aux Info Add Family Member Account A team member linked their free family account. `rdmchild` `famchild` Remove Family Member Account A team member unlinked their free family account. `detchild` `famchild` ### Files Actions related to creating documents. Event Description Action Object Type Aux Info Add File A file was uploaded to the account. `create` `file` ### Firewall rules Actions related to firewall settings. Event Description Action Object type Aux info Update Firewall Rules A firewall rule was added or updated. `updatfw` `account` ### Groups Actions related to creating, updating, and removing groups. Event Description Action Object Type Aux Info Create Group A group was created. `create` `group` group name Available for events that occurred after June 11, 2025. Delete Group A group was deleted. `delete` `group` group name Update Group A group was updated. `update` `group` group name Purge Deleted Group A group was marked to be purged. `purge` `group` Update Group Keyset A group keyset was replaced. `changeks` `group` ### Group membership Actions related to updating team members' group membership. Event Description Action Object Type Aux Info Join Group A user joined a group. `join` `gm` user ID, user UUID, user name, user email, user role <section> `R`: Group member `A`: Group manager </section> Leave Group A user left a group. `leave` `gm` user ID, user UUID, user name, user email Change Group Membership Role A user's group membership role was changed. `role` `gm` user ID, user UUID, user name, user email, user role <section> `R`: Group member `A`: Group manager </section> ### Group vault access Actions related to modifying groups' access to vaults. Event Description Action Object Type Aux Info Grant Group Vault Access A group was granted access to a vault. `grant` `gva` group ID, group UUID, Access Control List Revoke Group Vault Access A group's access to a vault was revoked. `revoke` `gva` group ID, group UUID Update Group Vault Access A group's vault access was updated. `update` `gva` group ID, group UUID, Access Control List ### Invites Actions related to inviting team members and guests. Event Description Action ObjectType AuxInfo Create Invite An invite was created. `create` `invite` The email address the invite was sent to. Update Invite An invite was updated. `update` `invite` The email address the invite was sent to. ### Items Actions related to creating, editing, archiving, and deleting items. Event Description Action ObjectType AuxInfo Patch Vault Items Vault items were added or updated. `patch` `items` Vault Content Version, number of items added or updated. Delete Trashed Vault Items Vault items in the trash were deleted. `delete` `items` Vault Content Version, number of items deleted. Purge Deleted Vault Items Deleted vault items were marked to be purged. `purge` `items` Number of items that were marked to be purged. Purge Vault Item History Archived vault items were marked to be purged. `purge` `itemhist` item ID, item UUID ### Item sharing Actions related to [sharing items](https://support.1password.com/share-items/). Event Description Action Object Type Aux Info Share Item An item was shared externally. `share` `item` vault ID, vault UUID, shared item UUID Delete Item Share A shared item link was deleted. `delshare` `item` vault ID, vault UUID, shared item UUID Update Item Share Settings The account's item sharing settings were updated. `uisas` `account` ### Managed companies Actions related to a managed service provider (MSP) creating, launching into, and unlinking managed companies. Event Description Action Object Type Aux Info Add Managed Company A managed company was added to an MSP account. `create` `mngdacc` Launch Into Managed Company An MSP technician launched into a managed company. `launchi` `mngdacc` The ID and UUID of the launched session. Unlink Managed Company A managed company was unlinked from an MSP account. `unlink` `mngdacc` ### Multi-factor authentication Actions related to enabling, updating, and removing multi-factor authentication. Event Description Action Object Type Aux Info Enable Multi-Factor Authentication Multi-factor authentication was enabled. `enblmfa` `user` multi-factor authentication ID, multi-factor authentication type Update Multi-Factor Authentication Multi-factor authentication was updated. `updatmfa` `user` multi-factor authentication ID, multi-factor authentication type Disable Multi-Factor Authentication Multi-factor authentication was disabled. `disblmfa` `user` multi-factor authentication ID, multi-factor authentication type Disable Multi-Factor Authentication For All Users Multi-factor authentication was disabled for everyone in the account. `disblmfa` `account` Disable Multi-Factor Authentication Type For All Users Multi-factor authentication of a certain type was disabled for everyone in the account. `disblmfa` `account` multi-factor authentication type ### Packages Actions related to team members sending a copy of an item within 1Password. Event Description Action Object Type Aux Info Send Package A user sent an item to another user. `sendpkg` `user` package UUID ### Provisioning Actions related to provisioning new team members. Event Description Action Object Type Aux Info Send Provisioning Email A provisioning email was sent. `sendts` `user` Resend Provisioning Email A provisioning email was resent. `resendts` `user` Resend All Provisioning Emails All provisioning emails were resent. `prsndall` `invite` ### Reports Actions related to viewing and exporting reports. Event Description Action ObjectType AuxInfo Export Report A user exported a report. `export` `report` report UUID, report type View Report A user viewed a report. `view` `report` report UUID, report type ### Service accounts Actions related to adding service accounts. Event Description Action Object Type Aux Info Create Integration A service account was created. `create` `sa` The type of service account. Set Expiration Integration An expiration time was set for a user-managed service account. `expire` `sa` The type of service account. ### Service account tokens Actions related to registering, updating, and revoking access tokens for service accounts. Event Description Action Object Type Aux Info Create Token A service account token was registered. `create` `satoken` token name Rename Token A service account token name was updated. `trename` `satoken` token name Verify Token A service account token signature was registered. `tverify` `satoken` token name Revoke Token A service account token was revoked. `trevoke` `satoken` token name ### Sign-in tokens Actions related to creating, ratcheting, and signing in with sign-in tokens for Unlock with SSO. Event Description Action Object Type Aux Info Sign In With Sign-In Token A sign-in token was used to log in. `ssotknv` `ssotkn` ### Slack app Actions related to connecting or removing a Slack app. Event Description Action Object Type Aux Info Enable Slack App A Slack app was connected to the account. `create` `slackapp` Disable Slack App A Slack app was removed from the account. `delete` `slackapp` Update Slack App A connected Slack app was updated. `update` `slackapp` ### SSO settings Actions related to setting up [Unlock with SSO](https://support.1password.com/sso-get-started/). Event Description Action Object Type Aux Info Enable SSO Unlock with SSO was enabled. `enblsso` `sso` Disable SSO Unlock with SSO was disabled. `disblsso` `sso` Change SSO Authentication Policy The SSO authentication policy was changed. `chngpsso` `sso` Change SSO Grace Period Authentication Count The SSO grace period authentication count was changed. `chngasso` `sso` Change SSO Grace Period Duration The SSO grace period duration was changed. `chngdsso` `sso` Add an SSO Group. An SSO group was added. `addgsso` `sso` group UUID Delete an SSO Group. An SSO group was deleted. `delgsso` `sso` group UUID ### Stripe cards Actions related to creating, updating, and removing Stripe cards. Event Description Action Object Type Aux Info Add Card A new Stripe card was created. `create` `card` card ID, card UID Update Card A Stripe card was updated. `update` `card` card ID, card UID Delete Card A Stripe card was deleted. `delete` `card` card ID, card UID ### Stripe payment methods Actions related to adding Stripe payment methods. Event Description Action Object Type Aux Info Add Payment Method A new Stripe payment method was created. `create` `pm` payment method ID, payment method UUID Delete Payment Method A Stripe payment method was deleted. `delete` `pm` payment method ID, payment method UUID ### Stripe subscriptions Actions related to creating, updating, and canceling Stripe subscriptions. Event Description Action Object Type Aux Info Create Subscription A new Stripe subscription was created. `create` `sub` subscription ID, subscription UUID Update Subscription A Stripe subscription was updated. `update` `sub` subscription ID, subscription UUID Cancel Subscription A Stripe subscription was canceled. `cancel` `sub` subscription ID, subscription UUID ### Templates Actions related to adding, updating, hiding, and deleting templates. Event Description Action Object Type Aux Info Add Template A template was added. `create` `template` template name Update Template A template was updated. `update` `template` template name Hide Template A template was hidden. `hide` `template` template name Unhide Template A template was shown (after being hidden). `unhide` `template` template name Delete Template A template was deleted. `delete` `template` template name ### Unknown Unknown events. Event Description Action ObjectType AuxInfo Unknown Events An unknown action occurred. `unknown` `unknown` ### Users Actions related to changes to team members' accounts attributes. Event Description Action Object Type Aux Info Upgrade User A guest was promoted to a family or team member. `upguest` `user` Change User State From A user's state was changed. `verify`, `join`, `activate`, `reactive`, `suspend`, `delete`, or `beginr` `user` Begin User Recovery A user recovery was initiated. `beginr` `user` Complete User Recovery A user recovery was completed. `completr` `user` Cancel User Recovery A user recovery was canceled. `cancelr` `user` Mark User Away For Travel A user was marked as away for travel. `trvlaway` `user` Mark User Back From Travel A user was marked as back from travel. `trvlback` `user` Change User Keyset A user's keyset changed. `changeks` `user` Change 1Password Account Password A user changed their 1Password account password. `changemp` `user` Change Secret Key A user changed their Secret Key. `changesk` `user` Change Name A user changed their name. `changenm` `user` Change Language A user changed their preferred language. `changela` `user` Enroll Trusted Device A user set up a trusted device to unlock with SSO. `tdvcsso` `user` device UUID Set up Single Sign-On Authentication A user set up their 1Password account to unlock with SSO. `sdvcsso` `user` ### User migration Actions related to migrating users. Event Description Action Object Type Aux Info Migrating User Created A user migration was started. `create` `miguser` user email Migrating User Complete A user migration was marked complete. `musercom` `miguser` Migrating User Declined A user migration was marked declined. `muserdec` `miguser` ### User vault access Actions related to changes to team members' access to vaults. Event Description Action Object Type Aux Info Grant User Vault Access A user was granted access to a vault. `grant` `uva` user ID, user UUID, user name, user email, Access Control List Revoke User Vault Access A user's access to a vault was revoked. `revoke` `uva` user ID, user UUID, user name, user email Update User Vault Access A user's vault access was updated. `update` `uva` user ID, user UUID, user name, user email, Access Control List ### User WebAuthn credentials (passkeys) {#passkeys} Actions relating to creating and deleting [passkeys](https://support.1password.com/save-use-passkeys/) used to sign in to 1Password. Event Description Action Object Type Aux Info Create User Webauthn Credential A passkey was created to sign in to 1Password. `create` `cred` Delete User Webauthn Credential A passkey used to sign in to 1Password was deleted. `delete` `cred` ### Vaults Actions related to creating, updating, and removing vaults. Event Description Action Object Type Aux Info Add Vault A vault was added. `create` `vault` Delete Vault A vault was deleted. `delete` `vault` Mark Vault To Be Purged A vault was marked for purging. `purge` `vault` Update Client Access The client access value for a vault was updated. `update` `vault` The new client access value. Update Attributes A vault name or description was changed. `updatea` `vault` Export Vault A vault was exported. `export` `vault` ### Verified domain Actions related to verifying domains. Event Description Action ObjectType AuxInfo Add Verified Domain A domain was verified. `vrfydmn` `account` domain Update Verified Domain A verified domain was updated. `uvrfydmn` `account` domain Delete Verified Domain A verified domain was removed. `dvrfydmn` `account` domain ## Appendix ### Action values Possible values for `action` include: API output Action `activate` Activate `addgsso` Add an SSO group `begin` Begin `beginr` Begin recovery `cancel` Cancel `cancelr` Cancel recovery `changeks` Change keyset `changela` Change language `changemp` Change 1Password account password `changenm` Change name `changesk` Change Secret Key `chngasso` Change SSO grace period authentication count `chngdsso` Change SSO authentication policy `chngpsso` Change SSO grace period duration `complete` Complete `completr` Complete recovery `convert` Convert `create` Create `dealldev` Deauthorize all devices `delete` Delete `delgsso` Delete an SSO Group `delshare` Delete shared item link `deolddev` Deauthorize old devices `detchild` Remove family member account `disblduo` Disable Duo `disblmfa` Disable multi-factor authentication `disblsso` Disable SSO `dlgsess` Delegate a new session `dvrfydmn` Delete verified domain `enblduo` Enable Duo `enablmfa` Enable multi-factor authentication `enblsso` Enable SSO `expire` Expire `export` Export `grant` Grant `hide` Hide `join` Join `launchi` Launch into managed company `leave` Leave `musercom` Complete migrating user API output Action `muserdec` Decline migrating user `patch` Modify or update `propose` Propose `provsn` Provision `prsndall` Resend all provisioning emails `purge` Permanently delete `rdmchild` Add family member account `reactive` Reactivate `reauth` Reauthorize `resendts` Resend provisioning email `revoke` Revoke `role` Update group membership role `sdvcsso` Set up SSO authentication `sendpkg` Send an item to another user `sendts` Send provisioning email `share` Share an item externally `ssotkn` Create sign-in token `ssotknr` Ratchet sign-in token `ssotknv` Sign in with sign-in token `suspend` Suspend `tdvcsso` Enroll trusted device `trename` Rename token `trevoke` Revoke token `trvlaway` Set as away for travel `trvlback` Set as back from travel `tverify` Verify token signature `uisas` Update item sharing administrator settings `unhide` Unhide `unknown` Unknown `unlink` Unlink managed company `updatduo` Update Duo `update` Update `updatea` Update attributes `updatfw` Update firewall rules `updatmfa` Update multi-factor authentication `upguest` Update guest `uvrfydmn` Update verified domain `view` View `verify` Verify `vrfydmn` Add verified domain ### Object values Possible values for `objectType` include: API output Object `account` 1Password account `card` Stripe card `cred` Credentials `device` Device `dlgdsess` Delegated session `ec` Email change `famchild` Linked family account `file` File `gm` Group membership `group` Group `gva` Group vault access `invite` Invite `item` Item `itemhist` Item history `items` Items `mngdacc` Managed account `miguser` Migrating user API output Object `mngdacc` Managed account `miguser` Migrating user `plan` Plan `pm` Stripe payment method `report` Report `sa` Service account `satoken` Service account token `slackapp` Slack app `sso` SSO `ssotkn` SSO token `sub` Stripe subscription `template` Template `user` User `uva` User vault access `vault` Vault `vaultkey` Vault key --- ## Authorization Every call to the 1Password Events API must be authorized with a valid [JWT-encoded ](https://datatracker.ietf.org/doc/html/rfc7519) bearer token in the HTTP [request header](/docs/events-api/request-headers/). The token authenticates the client and authorizes it to access specific resources (events), without exposing 1Password account credentials. ## Pass bearer tokens in your API requests Bearer tokens are passed to the Events API through the `Authorization` header in your request. ### Step 1: Get a bearer token You'll get a bearer token when you [set up a new Events Reporting integration](/docs/events-api/get-started#step-1-set-up-an-events-reporting-integration), or when you [issue a new token](#issue-a-bearer-token) in an existing integration. When you generate the token, you'll choose which events the token is scoped to, then save the token in 1Password. After you set up the integration, you can also [issue or revoke tokens](#manage-bearer-tokens) at any time. ### Step 2: Create an API request When you make a call to the Events API, you must include the `Authorization` [request header](/docs/events-api/request-headers/) with your bearer token. The following example uses [curl ](https://curl.se/) on the command line to make a GET request to the [`introspect` endpoint](/docs/events-api/reference#get-apiv2authintrospect). API calls to this endpoint allow you to check that your bearer token is valid and confirm which events it's authorized to access. 1. In your terminal, format your curl request using the following structure: ```shell [{ "badge": 1, "color": "tangerine", "lineNo": 2, "substr": "<base_url>" }, { "badge": 2, "color": "lagoon", "lineNo": 3, "substr": "<YOUR_BEARER_TOKEN>" }] curl --request GET \ --url <base_url>/api/v2/auth/introspect \ --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' ``` 2. Replace the {'<base_url>'} placeholder in the endpoint with the [events URL for your 1Password account](/docs/events-api/servers/). 3. Replace {'<YOUR_BEARER_TOKEN>'} in the `Authorization` header with the token for your Events Reporting integration. - Option 1: Copy the credential field from the bearer token you saved in 1Password, then paste it in the authorization header. For example: ```shell [{ "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjNyaTN0NDR0anZvZmNmbWc0Z2tsNWk2b2FpIiwidHlwIjoiSldUIn0..." }] --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjNyaTN0NDR0anZvZmNmbWc0Z2tsNWk2b2FpIiwidHlwIjoiSldUIn0...' ``` The `...` at the end of the bearer token here indicates it's been truncated for the example. You'll need to include the full credential string for your token. - Option 2: [Use an environment variable to load your API token](/docs/events-api/generic-scripts#usage) to avoid revealing your bearer token in plaintext. You'll need to use double quotes for the authorization header to allow for variable expansion. For example: ```shell [{ "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "${EVENTS_API_TOKEN}" }] --header "Authorization: Bearer ${EVENTS_API_TOKEN}" ``` ### Step 3: Send the API request Send the API request from the terminal. For example: ```shell [{ "badge": 1, "color": "tangerine", "lineNo": 2, "substr": "https://events.1password.com" }, { "badge": 2, "color": "lagoon", "lineNo": 3, "substr": "${EVENTS_API_TOKEN}" }] curl --request GET \ --url https://events.1password.com/api/v2/auth/introspect \ --header "Authorization: Bearer ${EVENTS_API_TOKEN}" ``` If you've installed [jq ](https://jqlang.github.io/jq/), you can add `| jq` at the end of your request to pretty-print the JSON response. If your token is authenticated, the API will return a [`200` response](/docs/events-api/reference#responses) that includes the events (features) scoped to your token. For example: ```json { "uuid": "OK41XEGLRTH4YKO5YRTCPNX3IU", "issued_at": "2025-10-17T16:32:50-03:00", "features": [ "auditevents", "itemusages", "signinattempts" ], "account_uuid": "M4E2SWNZAZFTRGQGDNS2E5A4MU" } ``` If you get a `401 Unauthorized` error, make sure your bearer token is in the `Authorization` header and is formatted correctly. Learn more about [status codes in the Events API](/docs/events-api/status-codes/). ## Manage bearer tokens After you set up your Events Reporting integration, you can [issue](#issue-a-bearer-token) additional bearer tokens, [revoke](#revoke-a-bearer-token) tokens, and [verify the scope](#verify-the-scope-of-a-bearer-token) of existing tokens. ### Issue a bearer token To issue a new bearer token for an existing integration: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select **[Integrations](https://start.1password.com/integrations/active)** in the sidebar. 2. Choose the Events Reporting integration where you want to issue a token and select **Add a token**. 3. Set up a new bearer token: - **Token Name**: Enter a name for the token. - **Expires After**: (Optional) Choose when the token will expire: 30 days, 90 days, or 180 days. The default setting is Never. - **Events to Report**: Choose which events the token can access. The default setting includes all events: sign-in attempts, item usages, and audit events. 4. Select **Issue Token**. 5. On the "Save your token" page, select **Save in 1Password**. Choose the vault where you want to save your token, then select **Save**. Your bearer token will be saved as an API Credential item in 1Password. If you set a bearer token to expire, you can also edit the item you saved in 1Password if you want to add the token's expiry date. ### Revoke a bearer token :::caution Your SIEM will stop ingesting events after a token is revoked. To minimize downtime, issue a replacement token before you revoke one. ::: To revoke a bearer token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select **[Integrations](https://start.1password.com/integrations/active)** in the sidebar. 2. Choose the Events Reporting integration where you want to revoke a token. 3. Select the gear button next to the token you want to revoke, then select **Revoke**. ### Verify the scope of a bearer token To verify a bearer token's scope, check the integration details on 1Password.com: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select **[Integrations](https://start.1password.com/integrations/active)** in the sidebar. 2. Choose the Events Reporting integration where you want to verify the scope of a token. 3. Locate your bearer token in the Tokens section and check which events it can access. You will also see when or if the token is set to expire. Alternatively, you can make a [GET request to the introspection endpoint](/docs/events-api/reference#get-apiv2authintrospect) to verify which events are scoped to the token. --- ## About the Events API beta The 1Password Events API v3 (version 3) beta is a REST-style HTTP API that follows the [OpenAPI 3.0 ](https://spec.openapis.org/oas/latest.html) specification. All requests are made over HTTPS and return JSON responses. The beta introduces a [new v3 versioned endpoint](/docs/events-api/beta/reference/get-v3-audit-events): - `GET /api/v3/auditevents` This endpoint returns audit events for actions performed by team members in a 1Password account. Each event describes: - Who performed the action (the actor). - What was affected (one or more target entities). - Where and how the action occurred (context about the account, location, client, device, and session). The beta API can be used alongside the existing Events API. The v1 and v2 endpoints for audit events, item usages, and sign-in attempts remain available. ## Request methods The beta API currently supports a single HTTP method (GET) to retrieve audit events and uses query parameters for pagination and time filters. The `/api/v3/auditevents` beta endpoint uses GET with query parameters for pagination and time filters. :::info The v1 and v2 API endpoints continue to use POST requests with a cursor object in the request body. ::: ## Servers and URLs The v3 beta endpoint is currently hosted on the same Events API servers as the production API. Your base URL depends on the [region](https://support.1password.com/regions/) where your 1Password account is hosted: | If your account is hosted on: | Your base URL is: | | --- | --- | | `1password.com` | `https://events.1password.com` | | `ent.1password.com` | `https://events.ent.1password.com` | | `1password.ca` | `https://events.1password.ca` | | `1password.eu` | `https://events.1password.eu` | To call the beta endpoint, append the v3 path to your base URL: ```text $BASE_URL/api/v3/auditevents ``` All requests must be made over HTTPS. :::info It's possible these servers could change during the beta or when the v3 endpoint moves to production. You can use the [Events API beta roadmap and changelog](/docs/events-api/beta/roadmap) to track changes. ::: ## Endpoints The v3 beta API uses the following endpoint: - [`GET /api/v3/auditevents`](/docs/events-api/beta/reference/get-v3-audit-events): Retrieve audit events for actions performed by team members within a 1Password account. Item usage and sign-in attempt events remain available through the existing v1 and v2 endpoints. ## Authorization All calls to the v3 beta endpoint must be authorized with a valid [JWT-encoded ](https://datatracker.ietf.org/doc/html/rfc7519) bearer token in the [`Authorization` header](#request-headers). The token must be scoped to include audit events. ## Request headers Requests to the beta endpoint require the `Authorization` header: ```shell Authorization: Bearer $EVENTS_API_TOKEN. ``` If your bearer token is missing, malformed, or invalid, the API will return a `401 Unauthorized` response. ## Pagination The beta API uses cursor-based pagination passed in the query string. ### Query parameters The v3 `auditevents` endpoint accepts the following optional query parameters: - `page_size`: The maximum number of events to return in a single response. - `start_time`: The earliest timestamp to include in the result set (inclusive). - `end_time`: The latest timestamp to include in the result set (inclusive). - `next_page_token`: An opaque token that identifies the next page of results to retrieve. :::info Data collection for the `/api/v3/auditevents` beta endpoint started December 1, 2025. To access event data prior to that date, you'll need to use the [`/api/v2/auditevents` production endpoint](/docs/events-api/reference#post-apiv2auditevents). ::: ### Response metadata Every `200` successful response includes a `meta` object with pagination metadata: - `next_page_token`: A token you can pass to the next request to retrieve the next page of results. - `has_more`: A boolean value that indicates whether additional pages are available (`true` or `false`). When `has_more` is `true`, you can continue making requests with `next_page_token` until there are no more events, indicated by `"has_more": false`. ### Pagination workflow The following example shows a typical pagination workflow: 1. Initial request: Make A GET call to `/api/v3/auditevents` with any combination of `page_size`, `start_time`, and `end_time` parameters you need. Note that data collection for this endpoint started December 1, 2025. 2. Check the response: Process the `audit_events` and check the `has_more` and `next_page_token` metadata. 3. Subsequent requests: If `has_more` is `true`, call the endpoint again. For example: ```shell curl --request GET \ --url "https://events.1password.com/api/v3/auditevents?next_page_token=eyJQYWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLCJTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQ0MCwiVGllQnJlYWtlciI6IkpaUjdaNDNMN1ZGVDVLVE0zRURBRURSRlBRIn0" \ --header "Authorization: Bearer $EVENTS_API_TOKEN" ``` Repeat until `has_more` is `false` and you’ve retrieved all events for the requested interval. Make sure not to use the `start_time` and `end_time` query parameters with the `next_page_token` query parameter. Doing so will result in a `400` bad request error. ## Rate limits Requests to the beta endpoint are rate limited to: - 600 requests per minute - 30,000 requests per hour The API uses standard HTTP headers to communicate your current rate limit window and remaining quota. Responses from `GET /api/v3/auditevents` may include the following headers: - `RateLimit-Limit`: The total number of requests allowed for the current time window. - `RateLimit-Remaining`: How many requests you can still make in the current window. - `RateLimit-Reset`: The Unix timestamp (in seconds) that indicates when the current rate limit window will reset. If you exceed the allowed rate, the API returns a `429 Too Many Requests` response. The `429` response includes the following header: `Retry-After`: Indicates how many seconds to wait before making another request. When you receive `429 Too Many Requests`, you should: 1. Stop sending additional requests to the endpoint. 2. Wait for the number of seconds specified in the `Retry-After` header. 3. Resume requests, ideally with backoff and retry logic in your client. --- ## Events API beta roadmap and changelog :::caution Beta features are not guaranteed The purpose of this roadmap is to provide beta testers with information about new or improved features that are available for testing. Beta features and improvements may be added, changed, or removed at any time and are not intended to be used in production. You can use the [beta changelog](#beta-changelog) to track changes. ::: You can use the beta roadmap to track the phased rollout of new and improved features planned for the Events API. This page will be updated periodically to indicate when: - A new or improved feature is ready for public beta testing - A beta feature moves into production - A planned feature is added, changed, or removed from the roadmap ## Planned features | Feature area | Plan | Phase/Status | Additional information | | --- | --- | ---| --- | | Audit events | Create new v3 endpoint for audit events, based on updated audit logging model. | Public beta | Beta endpoint available for testing: [`GET /api/v3/auditevents`](/docs/events-api/beta/reference/get-v3-audit-events). | | Audit log | Rename Activity Log to Audit Log and update to use new audit logging model. | Public beta | Learn more about the [beta audit log](https://support.1password.com/audit-log/). | | Item usages | Add item usage events to the beta. | Coming soon | | | Sign-in attempts | Add sign-in attempt events to the beta. | Coming soon | | | 1Password SaaS Manager (formerly Trelica) | Add SaaS Manager events to Events API and audit log. | Coming soon | | | 1Password Device Trust (Kolide) | Add Device Trust events to Events API and audit log. | Coming soon | | ## Beta changelog This section includes information about additive and breaking changes made to the v3 Events API throughout the beta, starting from the public beta release. ### Version 3.0.0 (2026-01-13) {#v3.0.0} Public release of the Events API v3 beta. - **Specification file**: [1Password Events API specifications (3.0.0)](https://i.1password.com/media/1password-events-reporting/1password-events-api_3.0.0.yaml) - **Summary**: We've launched the v3 beta of the 1Password Events API. The beta introduces a new audit logging model that provides a more comprehensive view of the actions being performed in a 1Password account. - **Details**: Key features include: - A new [v3 audit events beta endpoint](/docs/events-api/beta/reference/get-v3-audit-events): `/api/v3/auditevents`. This endpoint can return structured audit event data starting from December 1, 2025. Audit event data includes information about who performed an action, what was affected, and context about where and how the action occurred. - A new `GET` HTTP method for audit events. - Cursor-based pagination with query parameters for `page_size`, `start_time`, `end_time`, and `next_page`. - A new [beta audit log](https://support.1password.com/audit-log/) to monitor events that happen on your team from your 1Password.com account. --- ## Get started with the 1Password Events API (beta) # Get started with the 1Password Events API (Beta) :::info This content is for testing the v3 audit events beta endpoint. See how to [get started with the production version (v2)](/docs/events-api/get-started/) if you don't want to use the beta. ::: You can use the 1Password Events beta API to retrieve audit events from your 1Password Business account and send them to your security information and event management (SIEM) system. The beta API introduces a [new audit events endpoint](/docs/events-api/beta/reference/get-v3-audit-events) (`/api/v3/auditevents`) that uses the HTTP GET method and cursor-based pagination with query parameters. This beta endpoint returns structured audit event data beginning December 1, 2025. The data includes information about the actor, the affected entities, and contextual information about the account, where the session originated, and more for each event. [Learn more about the Events API v3 beta.](/docs/events-api/beta/about-v3-beta) ## Requirements Before you get started with the beta API, you’ll need to have: - [A 1Password Business account.](https://1password.com/pricing/password-manager) - An [owner](https://support.1password.com/groups/#owners) or [administrator](https://support.1password.com/groups/#administrators) role in your 1Password account. - A [JWT bearer token (Events API token)](/docs/events-api/authorization#manage-bearer-tokens) that’s authorized to access audit events for your account. If you already use the Events API with other endpoint versions, you can reuse the same Events Reporting integration and bearer token with the v3 beta endpoint. Make sure your bearer token is scoped for audit events. ## Step 1: Set up an Events Reporting integration If you haven’t set up Events Reporting yet, [create a new integration](/docs/events-api/get-started#step-1-set-up-an-events-reporting-integration) in your 1Password Business account and issue a bearer token. Save the token in 1Password, then load it into your environment when making API calls. If you already have Events Reporting set up for your 1Password account, review the integration details to confirm: - The integration is active. - Your bearer token is active and scoped to access audit events. ## Step 2: Find your Events API base URL The `/api/v3/auditevents` beta endpoint currently uses the same Events API servers as the v2 production endpoint. Choose the base URL that matches the [region](https://support.1password.com/regions/) where your 1Password account is hosted: | If your account is hosted on: | Your base URL is: | | --- | --- | | `1password.com` | `https://events.1password.com` | | `ent.1password.com` | `https://events.ent.1password.com` | | `1password.ca` | `https://events.1password.ca` | | `1password.eu` | `https://events.1password.eu` | You’ll use this base URL together with the v3 `auditevents` path. For example: ```text https://events.1password.com/api/v3/auditevents ``` ## Step 3: Send a test request with curl You can send a test request with [curl ](https://curl.se/) on the command line to confirm your integration is working. :::info The v3 beta endpoint uses a different HTTP method for requests: - v3 beta endpoint: `GET /api/v3/auditevents` - v2 production endpoint: `POST /api/v2/auditevents` ::: ### 3.1: Create a curl request In your terminal, format your request using the following structure: ```shell curl --request GET \ --url "$BASE_URL/api/v3/auditevents?page_size={events_per_page}&start_time={start_time}&end_time={end_time}" \ --header "Authorization: Bearer $EVENTS_API_TOKEN" ``` Replace the placeholders with your own values: - `$BASE_URL`: The Events API base URL for your 1Password account. For example: `https://1password.com`. - `$EVENTS_API_TOKEN`: The bearer token for your Events Reporting integration. - `{events_per_page}`: (Optional) The maximum number of events to return in a single response. Use a value from `1` to `1000`. If you don’t include the `page_size` parameter, a default of `100` will be used. - `{start_time}`: (Optional) The date and time for when you want to start retrieving events, in [RFC 3339 format ](https://datatracker.ietf.org/doc/html/rfc3339). For example: `2026-01-01T00:00:00Z`. - `{end_time}`: (Optional) The date and time for when you want to stop retrieving events, in [RFC 3339 format ](https://datatracker.ietf.org/doc/html/rfc3339). For example: `2026-01-12T23:59:59Z`. If you omit the `start_time` and `end_time` parameters, the endpoint will return a page of events using the service-defined default time range. :::info Data collection for the `/api/v3/auditevents` beta endpoint started December 1, 2025. To access event data prior to that date, you'll need to make a [`POST` request to the `/api/v2/auditevents` production endpoint](/docs/events-api/reference#post-apiv2auditevents). ::: ### 3.2: Send a curl request The following example sends a GET request to the [`/api/v3/auditevents` endpoint](/docs/events-api/beta/reference/get-v3-audit-events), using the curl command structure from the example above. Adjust the query parameters as needed. ```json curl --request GET \ --url "$BASE_URL/api/v3/auditevents?page_size=1&start_time=2026-01-01T00:00:00Z&end_time=2026-01-12T23:59:59Z" \ --header "Authorization: Bearer $EVENTS_API_TOKEN" #code-result { "data": { "audit_events": [ { "action": "vault.vault-item.update", "actor": { "email": "wendy_appleseed@agilebits.com", "name": "Wendy Appleseed", "type": "user", "uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V" }, "category": "vault", "context": { "account": { "name": "AgileBits", "uuid": "VZSYVT2LGHTBWBQGUJAIZVRABM" }, "client": { "name": "1Password Extension", "version": "81118003" }, "device": { "model": "142.0.7444.23", "uuid": "katnz37usfc5i67fqekylwmcde" }, "location": { "city": "Toronto", "country": "Canada", "ip_address": "192.0.2.254", "latitude": 43.5991, "longitude": -79.4988, "region": "Ontario" }, "origin": "Admin Console", "os": { "name": "MacOSX", "version": "10.15" "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.1 Safari/605.1.15" }, "session": { "login_time": "2025-11-13T18:52:10.706588504Z", "uuid": "X6TARAEE2NGKFLMK5POQBZ4U2Q" } }, "targets": [ { "payload": { "type": "P", "uuid": "lc5fqgbrcm4plajd8mwncv2b3u" }, "type": "vault" } ], "timestamp": "2026-01-01T19:01:20.110679321Z", "uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM" } ] }, "meta": { "has_more": true, "next_page_token": "eyLMNWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLOPTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQRSTwiVGllQnJlYWtlciI6IkpaUjdaUVWMN1ZGVDVLVE0zRXYZRURSRlBRIn0" } } ``` For better readabilty, you can also provide the query parameters on separate lines using `--data-urlencode` flags. ```shell curl --request GET \ --url "$BASE_URL/api/v3/auditevents" \ --header "Authorization: Bearer $EVENTS_API_TOKEN" \ --data-urlencode "page_size=1" \ --data-urlencode "start_time=2026-01-01T00:00:00Z" \ --data-urlencode "end_time=2026-01-12T23:59:59Z" ``` ### 3.3: Review the response Review the response to confirm that the `audit_events` array contains the expected event data. If the response body is empty, try adjusting your `start_time` and `end_time` parameters. If there are more events available than can be returned in a single response, the beta endpoint returns a meta object that includes: - `next_page_token`: An opaque token you can pass in the next request to retrieve the next page of results. - `has_more`: A boolean value that indicates whether more pages are available (`true` or `false`). For example, the response to the curl request above includes the following meta object: ```json "meta": { "next_page_token": "eyLMNWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLOPTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQRSTwiVGllQnJlYWtlciI6IkpaUjdaUVWMN1ZGVDVLVE0zRXYZRURSRlBRIn0", "has_more": true } ``` To request the next page of results, use the `next_page_token` value as a query parameter. For example: ```shell curl --request GET \ --url "$BASE_URL/api/v3/auditevents?next_page_token=eyLMNWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLOPTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQRSTwiVGllQnJlYWtlciI6IkpaUjdaUVWMN1ZGVDVLVE0zRXYZRURSRlBRIn0" \ --header "Authorization: Bearer $EVENTS_API_TOKEN" ``` You can continue calling the endpoint with each `next_page_token` value that gets returned until `has_more` is `false`. Make sure not to include the `start_time` or `end_time` parameters in requests that use a `next_page_token`. Doing so will result in a `400` bad request error. To view HTTP status codes and rate limit in the responses, you can use the `--include` flag in your request. For example: ```shell curl --include --request GET... ``` ## Step 4: Test the beta endpoint After you’ve confirmed your Events API integration is working, you can test the beta `/api/v3/auditevents` endpoint with your SIEM. :::caution The v3 beta endpoint is stable for testing, but it's possible changes could be made during the beta that will break integrations. We don't recommend the beta for production use, but we do encourage beta testers to use v3 beta endpoint alongside the v2 production version and provide feedback. You can also use the [Events API beta roadmap and changelog](/docs/events-api/beta/roadmap) to track changes. ::: --- ## Get v3 audit events # Get v3 audit events (Beta) :::tip This API reference documents the latest version of the [1Password Events API beta specifications (3.0.0)](https://i.1password.com/media/1password-events-reporting/1password-events-api_3.0.0.yaml). Learn more [about the beta API](/docs/events-api/beta/about-v3-beta). ::: Retrieve v3 (version 3) audit events for actions performed by team members within a 1Password account. Method Endpoint URL `GET` `<base_url>/api/v3/auditevents` You can use this endpoint to determine who performed an action and when, like when a team member edits an item's password or invites another team member to a shared vault. ## Make a request ### Request header To make a request to the `/api/v3/auditevents` endpoint, you'll need to use the `Authorization` header with a [bearer token](/docs/events-api/authorization/) scoped to access audit events. ``` Authorization: Bearer YOUR_BEARER_TOKEN ``` ### Query parameters You can optionally use any of the following query parameters in your request: - `page_size`: Specify the number of events records to return per page, between 1 and 1000. - `start_time`: The date and time from which to start retrieving events. - `end_time`: The date and time to stop retrieving events. - `next_page_token`: Add a cursor token from a previous response to go to the next page of results. See the [query parameters schema](#query-parameters-schema) for more details. ### Example requests Example request with page size and start and end time parameters: ```shell curl --request GET \ --url https://events.1password.com/api/v3/auditevents?page_size=50&start_time=2026-01-01T00:00:00Z&end_time=2026-01-13T17:30:00Z \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' ``` Example request that includes a token to return the next page of events: ```shell curl --request GET \ --url "https://events.1password.com/api/v3/auditevents?next_page_token=aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" \ --header "Authorization: Bearer YOUR_BEARER_TOKEN" ``` ## Receive a response A successful response will include a subset of events matching your query parameters (if any exist), along with pagination metadata that indicates if there are more results (`true` or `false`). If true, the response will include a token you can use to request subsequent pages of events. If the response is successful but there aren't any events for the parameters you requested, the `audit_events` array will be empty (`[]`). ### HTTP status code Every request returns an [HTTP status code](/docs/events-api/status-codes) that indicates if the response was successful or there was a problem. ### Response headers The response may also include one or more of the following `RateLimit` response headers, as defined by the [IETF standards ](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html#name-header-specifications): - `Content-Type: application/json` - `RateLimit-Limit` - `Ratelimit-Remaining` - `RateLimit-Reset` - `Retry-After` (only in responses with a `429 Too Many Requests` error) You can use the `--include` flag in your request to view the HTTP status code and your remaining rate limit in the response. For example: ```shell curl --include --request GET... ``` ### Example responses A successful `200` response returns an array of [`AuditEventsResponse` objects](#auditeventsresponse-object) with the following high-level structure: ```json { "data": { "audit_events": [ { "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E", "timestamp": "2025-01-01T00:00:00Z", "context": { /* Context object */ }, "actor": { /* Actor object */ }, "category": "vault", "action": "vault.vault-item.update", "targets": [ /* Entity objects */ ] } ] }, "meta": { "next_page_token": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK", "has_more": true } } ``` Below is an example of a successful response that shows one event (a user edited an item in a shared vault). It includes response headers and metadata with a token to fetch the next page of results. ```json HTTP/2 200 content-type: application/json ratelimit-limit: 600 ratelimit-remaining: 599 ratelimit-reset: 1767735927 date: Tue, 13 Jan 2026 17:30:52 GMT { "data": { "audit_events": [ { "action": "vault.vault-item.update", "actor": { "email": "wendy_appleseed@agilebits.com", "name": "Wendy Appleseed", "type": "user", "uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V" }, "category": "vault", "context": { "account": { "name": "AgileBits", "uuid": "VZSYVT2LGHTBWBQGUJAIZVRABM" }, "client": { "name": "1Password Extension", "version": "81118003" }, "device": { "model": "142.0.7444.23", "uuid": "katnz37usfc5i67fqekylwmcde" }, "location": { "city": "Toronto", "country": "Canada", "ip_address": "192.0.2.254", "latitude": 43.5991, "longitude": -79.4988, "region": "Ontario" }, "origin": "Admin Console", "os": { "name": "MacOSX", "version": "15.7.1" "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.1 Safari/605.1.15" }, "session": { "login_time": "2025-11-13T18:52:10.706588504Z", "uuid": "X6TARAEE2NGKFLMK5POQBZ4U2Q" } }, "targets": [ { "payload": { "type": "P", "uuid": "lc5fqgbrcm4plajd8mwncv2b3u" }, "type": "vault" } ], "timestamp": "2026-01-01T19:01:20.110679321Z", "uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM" } ] }, "meta": { "has_more": true, "next_page_token": "eyLMNWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLOPTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQRSTwiVGllQnJlYWtlciI6IkpaUjdaUVWMN1ZGVDVLVE0zRXYZRURSRlBRIn0" } } ``` Example response headers when the rate limit of 600 requests per minute has been exceeded: ```json HTTP/1.1 429 Too Many Requests content-type: application/json ratelimit-limit: 600 ratelimit-remaining: 0 ratelimit-reset: 1768325512 retry-after: 60 date: Tue, 13 Jan 2026 17:30:52 GMT ``` ## Request schemas ### Query parameters {#query-parameters-schema} Name Type Required Description `page_size` integer No Maximum number of events records to return per page, from 1 to 1000. If the `page_size` parameter isn't include, the default of 100 will be used. `next_page_token` string No Opaque cursor token identifying the next page of results to retrieve. Do not use the `start_time` or `end_time` parameters with the `next_page_token`. Doing so will result in a `400` bad request error. `start_time` string (date-time) No The earliest timestamp (inclusive) from which to retrieve events. Invalid if `next_page_token` is specified. Uses the RFC 3339 standard . `end_time` string (date-time) No The latest timestamp (inclusive) for which to retrieve events. Invalid if `next_page_token` is specified. Uses the RFC 3339 standard . ## Response schemas ### Rate limit headers Header Type Required Description `RateLimit-Limit` integer No The request quota for the associated client in the current time window. `RateLimit-Remaining` integer No The remaining request quota for the associated client. `RateLimit-Reset` integer No Unix timestamp that indicates the number of seconds until the request quota is reset for the associated client. `Retry-After` integer No Number of seconds until the request quota is reset for the associated client. Only included in responses with the `429 Too Many Requests` rate limit error. ### AuditEventsResponse object Field Type Required Description `data` object Yes Container for the audit event data. `data.audit_events` array Yes Array of [`AuditEvent` objects](#auditevent-object). `meta` object Yes Pagination metadata for the response that can be used in subsequent requests. `meta.next_page_token` string No Opaque token used to retrieve the next page of results. Should be included in subsequent requests until `has_more` is false. `meta.has_more` boolean Yes Indicates if additional pages of results are available for retrieval (`true`) or not (`false`). #### AuditEventsResponse: AuditEvent object {#auditevent-object} Field Type Required Description `uuid` string Yes Unique identifier for the audit event. `timestamp` string (date-time) Yes The date and time when the event occurred. Uses the RFC 3339 standard . `context` object Yes A [`Context` object](#context-object) containing information about how the event was initiated. `actor` object Yes An [`Actor` object](#actor-object) describing who initiated the event. `category` string Yes High-level category of the event (for example, `report`). `action` string Yes Specific action taken (for example, `report.view`). `targets` array Yes Array of [`Entity` objects](#entity-object) that describe what was affected. #### AuditEventsResponse: Account object {#account-object} Field Type Required Description `uuid` string Yes UUID of the account. `name` string Yes Name of the account. `state` string Yes State of the account (for example, `A`). `type` string Yes Type of the account (for example, `B`). `domain` string Yes Domain associated with the account (for example, `1password.com`). #### AuditEventsResponse: Actor object {#actor-object} Field Type Required Description `type` string Yes The type of actor (for example, `user`). `uuid` string Yes UUID of the actor. `name` string No Display name of the actor, if available. `email` string No Email address of the actor, if available. `linked_account` object No An [`Account` object](#account-object) describing a related account, if any. #### AuditEventsResponse: Client object {#client-object} Field Type Required Description `name` string Yes Name of the client that was used. `version` string Yes Version of the client that was used. #### AuditEventsResponse: Context object {#context-object} Field Type Required Description `account` object Yes A [`ContextAccount` object](#contextaccount-object) describing the account associated with the event. `origin` string Yes The application or interface where the event occurred (for example, `password_manager`). `session` object No A [`Session` object](#session-object) describing the session in which the event occurred. `location` object Yes A [`Location` object](#location-object) describing where the event originated. `device` object No A [`Device` object](#device-object) describing the device used to initiate the event. `client` object No A [`Client` object](#client-object) describing the 1Password client used (app or integration). `os` object No An [`OS` object](#os-object) describing the operating system. #### AuditEventsResponse: ContextAccount object {#contextaccount-object} Field Type Required Description `uuid` string Yes UUID of the account. `name` string Yes Name of the account. #### AuditEventsResponse: Device object {#device-object} Field Type Required Description `uuid` string Yes UUID of the device. `model` string Yes Model of the device. #### AuditEventsResponse: Entity object {#entity-object} Field Type Required Description `type` string Yes Type of entity affected by a given event. An entity may contain a number of additional properties specific to its type. For example: `report`, `user`, or other resource types. `payload` object Yes Additional properties describing the entity. #### AuditEventsResponse: Location object {#location-object} Field Type Required Description `ip_address` string Yes IP address from which the event originated. `country` string No Country associated with the IP address. `region` string No Region associated with the IP address. `city` string No City associated with the IP address. `latitude` number No Latitude of the location. `longitude` number No Longitude of the location. #### AuditEventsResponse: OS object {#os-object} Field Type Required Description `name` string Yes Name of the operating system that was used. `version` string Yes Version of the operating system that was used. `userAgent` string No Information about the operating system, such as software identification and environment details. #### AuditEventsResponse: Session object {#session-object} Field Type Required Description `uuid` string Yes UUID of the session. `login_time` string (date-time) Yes Time when the session was created. ### ErrorResponse object Field Type Required Description `Error` object No An [`Error` object](#error-object) containing the error message. #### ErrorResponse: Error object {#error-object} Field Type Required Description `Message` string No An error message. --- ## 1Password Events API changelog This changelog tracks notable changes to the 1Password Events API and provides information about when changes were made and what changed. ## Summary of changes | Version | Date | Type | Description | Details | |---------|------|------|-------------|---------| | 1.4.1 | September 2025 | Improvement | Added an account UUID property to the introspect response object. | [View details](#september-2025) | | 1.4.0 | November 2024 | New feature | Added V2 endpoints for sign-in attempts and item usage with external user and MSP support. (*Breaking change* *) | [View details](#november-2024) | | 1.3.0 | September 2024 | New feature | Added V2 audit events endpoint with external user and MSP support. (*Breaking change* *) | [View details](#september-2024) | | 1.2.0 | November 2023 | New feature | Added passkey credential support to audit events. | [View details](#november-2023) | | 1.2.0 | August 2023 | Improvement | Enhanced user details in audit event responses. | [View details](#august-2023) | | 1.2.0 | November 2022 | New feature | Added audit events endpoint and reporting capabilities. | [View details](#november-2022) | | 1.2.0 | March 2022 | Improvement | Added geolocation info and SSO actions. | [View details](#march-2022) | | 1.1.0 | September 2021 | Improvement | Added internal server error handling. | [View details](#september-2021) | | 1.1.0 | August 2021 | New feature | Added V2 introspection endpoint. (*Breaking change* *) | [View details](#august-2021) | | 1.0.0 | July 2021 | Initial release | Initial public release of the 1Password Events API. | [View details](#july-2021) | * Breaking changes are backwards-incompatible changes that require an upgrade to use. When breaking changes are released, we'll continue to support previous versions of the API and you can choose when to upgrade your API version. ## September 2025 (version 1.4.1) {#september-2025} Added a new `account_UUID` property to the introspect endpoint (/api/v2/auth/introspect). You can now confirm the account a bearer token was issued from. This is particularly relevant to managed service providers (MSPs) that manage multiple accounts. ## November 2024 (version 1.4.0 ) {#november-2024} Added new V2 endpoints with external user and MSP functionality: - POST /api/v2/signinattempts - POST /api/v2/itemusages Changes include: - New SignInAttemptV2 schema: - Added `account_uuid` field - Added `federated` sign-in type - Uses enhanced UserV2 schema - New ItemUsageV2 schema: - Added `account_uuid` field - Uses enhanced UserV2 schema - New SignInAttemptUserTypes enum for user type classification ### Breaking changes V2 endpoints introduce new required fields and response structures. If upgrading from V1: - Response schemas include new required fields - User objects now include type classification - New enums added for MSP functionality ### Migration impact V1 endpoints continue to be supported. Migration to V2 endpoints is only required if you're an MSP provider and you need to access MSP-related event data for your account or the accounts of your managed companies. New integrations can use V2 endpoints regardless of MSP needs. ## September 2024 (version 1.3.0) {#september-2024} Added new V2 audit events endpoint with MSP support: - POST /api/v2/auditevents Changes include: - New AuditEventV2 schema: - Added `actor_type` field - Added `actor_account_uuid` field - Added `account_uuid` field - Added AuditEventActorTypes enum - Added new actions: - `expire` - `launchi` - `unlink` - Added `mngdacc` object type for managed accounts ## November 2023 (version 1.2.0) {#november-2023} - Added "cred" object type for passkey authentication - Fixed latitude field name in Location schema ## August 2023 (version 1.2.0) {#august-2023} Enhanced AuditEvent schema with detailed user information: - Added `actor_details` - Added `object_details` - Added `aux_details` ## November 2022 (version 1.2.0) {#november-2022} - Added audit events endpoint (/api/v1/auditevents) - Added new schemas: - AuditEvent - AuditEventItems - AuditEventActions - AuditEventObjectTypes - Session ## March 2022 (version 1.2.0) {#march-2022} - Added Location object to sign-in attempts and item usage events: - `country` - `region` - `city` - `longitude` - `latitude` - Added new item usage actions: - `select-sso-provider` - `enter-item-edit-mode` ## September 2021 (version 1.1.0) {#september-2021} - Added 500 Internal Server Error response to all endpoints ## August 2021 (version 1.1.0) {#august-2021} Added V2 introspection endpoint: - New introspection endpoint (/api/v2/auth/introspect) - V1 endpoint marked as deprecated - Added IntrospectionV2 schema with consistent naming ## July 2021 (Version 1.0.0) {#july-2021} Initial [public release of the 1Password Events API](https://blog.1password.com/introducing-events-api/), including: - Introspection endpoint - JWT authentication - Item usage endpoint - Sign-in attempts endpoint - Cursor-based pagination --- ## Endpoints ## Endpoint structure Each API endpoint starts with a [base URL](/docs/events-api/servers/), followed by the resource or operation path: ```text [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "base_url" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "/path" }] base_url/path ``` Replace the base_url placeholder with the appropriate base URL for your 1Password account and use the path of the operation or resource you want to access: [`introspect`](/docs/events-api/reference#get-apiv2authintrospect), [`auditevents`](/docs/events-api/reference#post-apiv2auditevents), [`itemusages`](/docs/events-api/reference#post-apiv2itemusages), or [`signinattempts`](/docs/events-api/reference#post-apiv2signinattempts). For example, if your 1Password account is hosted on `ent.1password.com` and you want to retrieve a list of audit events, you would use the following URL to make a call to the `auditevents` endpoint: ```="Structure of an API endpoint" [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "https://events.ent.1password.com" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "/api/v2/auditevents" }] https://events.ent.1password.com/api/v2/auditevents ``` ## Endpoint versions The Events API supports both V1 and V2 endpoints for audit events, item usages, and sign-in attempts. The V2 endpoints in this reference provide additional information about users and accounts for managed service providers (MSPs). V1 endpoints remain fully supported for existing integrations that don't require the additional MSP account and user type information. Choose the appropriate version based on your needs: - Use V2 endpoints if you need MSP-related event data or if you're just starting with the Events API. - Use V1 endpoints if you have existing integrations and you don't require the additional MSP data. See the [API changelog](/docs/events-api/changelog/) to learn more about the changes in the V2 endpoints and previous versions of the API. --- ## 1Password Events API generic scripts :::info If you're new to Events Reporting, [learn how to get started with 1Password Events API](/docs/events-api/get-started/). ::: To help you get started with the 1Password Events API we've put together a [repository of example scripts](https://github.com/1Password/events-api-generic) across several languages, including [JavaScript](https://github.com/1Password/events-api-generic/blob/main/eventsapi.js), [Python](https://github.com/1Password/events-api-generic/blob/main/eventsapi.py), [Ruby](https://github.com/1Password/events-api-generic/blob/main/eventsapi.rb), [Go](https://github.com/1Password/events-api-generic/blob/main/eventsapi.go), and [PHP](https://github.com/1Password/events-api-generic/blob/main/eventsapi.php). The scripts will print up to 20 sign-in attempts and item usage events from the last 24 hours. ## Requirements Before implementing any of the examples, or your own scripts, you'll need to generate a bearer token and store it in your 1Password account. To get a bearer token, you can: - [Set up a new Events Reporting integration.](/docs/events-api/get-started#step-1-set-up-an-events-reporting-integration) - [Issue a new token](/docs/events-api/authorization#issue-a-bearer-token) in an existing integration. - [Generate a token with 1Password CLI.](/docs/cli/reference/management-commands/events-api#events-api-create) ## Usage All scripts use the `EVENTS_API_TOKEN` environment variable to load your API token. We recommend setting `EVENTS_API_TOKEN` to a [secret reference](/docs/cli/secret-reference-syntax/) that points to where your bearer token is saved in 1Password, to avoid revealing the token in plaintext. Then you can use [`op run`](/docs/cli/reference/commands/run/) with [1Password CLI](/docs/cli/) to securely provision the token at runtime. [Learn more about securely loading secrets from the environment.](/docs/cli/secrets-environment-variables/) For example, to set the [`EVENTS_API_TOKEN` environment variable](/docs/cli/secrets-environment-variables#use-environment-env-files) with an environment file, then use [`op run`](/docs/cli/reference/commands/run/) to run the PHP `eventsapi.php` script with the variable provisioned: ```shell title="events.env" EVENTS_API_TOKEN="op://Vault/Item/token" ``` ``` op run --env-file="./events.env" -- php eventsapi.php ``` To export the [`EVENTS_API_TOKEN` environment variable](/docs/cli/secrets-environment-variables#export-environment-variables), then use [`op run`](/docs/cli/reference/commands/run/) to run the Go `eventsapi.go` script with the variable provisioned: **bash, sh, zsh, fish:** ```shell EVENTS_API_TOKEN="op://Vault/Item/token" op run -- go run eventsapi.go ``` **Powershell:** 1. Export the necessary environment variables: ```powershell $Env:EVENTS_API_TOKEN = "op://Vault/Item/token" ``` 2. Run op run -- with your command for starting the app: ```powershell op run -- go run eventsapi.go ``` ## Learn more - [Get started with the 1Password Events API](/docs/events-api/get-started/) - [Issue or revoke bearer tokens for the Events API](/docs/events-api/authorization#manage-bearer-tokens) - [About 1Password Events Reporting security](https://support.1password.com/events-reporting-security/) --- ## Get started with the 1Password Events API You can use the 1Password Events API to set up an integration between your 1Password Business account and your security information and event management (SIEM) system. ## Requirements Before you get started, you'll need to [sign up for a 1Password Business account](https://1password.com/pricing/password-manager). If you already have a business account, you'll need to be an [owner](https://support.1password.com/1password-glossary#owner) or [administrator](https://support.1password.com/1password-glossary#administrator) to set up an Events Reporting integration. ## Step 1: Set up an Events Reporting integration You can set up an Events Reporting integration in your 1Password Business account: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Integrations**](https://start.1password.com/integrations/directory) in the sidebar. If you've set up other integrations in your account, you'll also need to select **Directory** on the Integrations page. 3. In the Events Reporting section, choose your SIEM from the list. If your SIEM isn't listed, select **Other**. 4. Enter a name for the integration, then select **Add Integration**. 5. Set up a bearer token: - **Token Name**: Enter a name for the token. - **Expires After**: (Optional) Choose when the token will expire: 30 days, 90 days, or 180 days. The default setting is Never. - **Events to Report**: Choose which events the token can access. The default scope includes all events: sign-in attempts, item usages, and audit events. 6. Select **Issue Token**. 7. On the "Save your token" page, select **Save in 1Password**. Choose the vault where you want to save your token, then select **Save**. Your bearer token will be saved as an API Credential item in 1Password. 8. Select **View Integration Details**. You can issue or revoke bearer tokens for your Events Reporting integration at any time. Learn more about [how to manage bearer tokens](/docs/events-api/authorization#manage-bearer-tokens). ## Step 2: Test the integration Before you connect your 1Password account with your SIEM, you can send a test request to the Events API using [curl ](https://curl.se/) on the command line. Specify the [endpoint](/docs/events-api/endpoints/) along with any required [request headers](/docs/events-api/request-headers/) and data. ### 1. Create a curl request In your terminal, format your curl request using the following structure: ```shell [{ "badge": 1, "color": "intrepidblue", "lineNo": 1, "substr": "<METHOD>" }, { "badge": 2, "color": "sunbeam", "lineNo": 2, "substr": "<base_url>" }, { "badge": 3, "color": "lagoon", "lineNo": 2, "substr": "<path>" }, { "badge": 4, "color": "dahlia", "lineNo": 3, "substr": "<YOUR_BEARER_TOKEN>" }, { "badge": 5, "color": "bitsblue", "lineNo": 6, "substr": "<number_of_records>" }, { "badge": 6, "color": "tangerine", "lineNo": 7, "substr": "<YYYY-MM-DDTHH:MM:SSZ>" }, { "badge": 6, "color": "tangerine", "lineNo": 8, "substr": "<YYYY-MM-DDTHH:MM:SSZ>" }] curl --request <METHOD> \ --url <base_url>/<path> \ --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \ --header 'Content-Type: application/json' \ --data '{ "limit": <number_of_records>, "start_time": "<YYYY-MM-DDTHH:MM:SSZ>", "end_time": "<YYYY-MM-DDTHH:MM:SSZ>" }' ``` The `Content-Type` header and the `--data` flag with [pagination](/docs/events-api/pagination/) content are only used in `POST` requests to the Events API. Replace the highlighted content with your preferred values: {'<METHOD>'} The [HTTP request method](/docs/events-api/request-methods/) you want to use for your request. For example: `POST`. {'<base_url>'} The [base URL](/docs/events-api/servers/) of the server used for events in your 1Password account. For example: `https://events.1password.com`. {'<path>'} The path of the [endpoint](/docs/events-api/endpoints/) you want to use. For example: `/api/v2/signinattempts`. {'<YOUR_BEARER_TOKEN>'}: The bearer token you generated in [step 1](#step-1-set-up-an-events-reporting-integration). You can use one of the following options: - Option 1: Copy the credential field from the bearer token you saved in 1Password, then paste it in the authorization header. For example: ```shell [{ "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjNyaTN0NDR0anZvZmNmbWc0Z2tsNWk2b2FpIiwidHlwIjoiSldUIn0..." }] --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjNyaTN0NDR0anZvZmNmbWc0Z2tsNWk2b2FpIiwidHlwIjoiSldUIn0...' ``` The `...` at the end of the bearer token here indicates it's been truncated for the example. You'll need to include the full credential string for your token. - Option 2: [Use an environment variable to load your API token](/docs/events-api/generic-scripts#usage) to avoid revealing your bearer token in plaintext. You'll need to use double quotes for the authorization header to allow for variable expansion. For example: ```shell [{ "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "${EVENTS_API_TOKEN}" }] --header "Authorization: Bearer ${EVENTS_API_TOKEN}" ``` {'<number_of_records>'} The optional [pagination limit](/docs/events-api/pagination/) for the maximum number of event records you want returned per page. (POST requests only.) Choose a value from `1` to `1000`. {'<YYYY-MM-DDTHH:MM:SSZ>'} The optional [RFC 3339-formatted ](https://datatracker.ietf.org/doc/html/rfc3339) date and time (UTC) for when you want to start and stop retrieving events. (POST requests only.) For example: `2025-10-31T09:00:00Z`. The pagination limit, start time, and end time data is all optional. If you don't want to include them in your POST request, use an empty request body for the `--data` flag: ```shell --data '{}' ``` ### 2. Send a curl request Send your formatted curl request from the terminal. The following example sends a POST request to the [`signinattempts` endpoint](/docs/events-api/reference#post-apiv2signinattempts), using the curl command structure from the example above. ```json curl --request POST \ --url https://events.1password.com/api/v2/signinattempts \ --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6Imt6aXJ4NHQ0Mm1laDVwbmFhcm4yYjZucXN1IiwidHlwIjoiSldUIn0...' \ --header 'Content-Type: application/json' \ --data '{ "limit": 1, "start_time": "2025-10-31T09:00:00Z", "end_time": "2025-10-31T17:00:00Z" }' #code-result { "cursor": "ZX8DAQETRWxhc3RpY3NlYXJjaEN1cnNvcgH_gAABBQEFTGltaXQBBAABCVN0YXJ0VGltZQH_ggABB0VuZFRpbWUB_4IAAQtTZWFyY2hBZnRlcgEEAAEKVGllQnJlYWtlcgEMAAAACv-BBQEC_4QAAABL_4ABAgEPAQAAAA7gjFYQAAAAAP7UAQ8BAAAADuCSBYgAAAAA_tQB-gM0JEhDqgEaQlRYUFUzM1ZOTkJLVERST0lGRUVUQkZQNlUA", "has_more": true, "items": [ { "uuid": "BTXPU33VNNBKTDROIFEETBFP6U", "session_uuid": "DU72R2RHZRHUTOYHMG44EDG4UI", "timestamp": "2025-10-31T13:45:49.203617068Z", "country": "CA", "category": "success", "type": "credentials_ok", "details": null, "client": { "app_name": "1Password for Mac", "app_version": "81118011", "platform_name": "Wendy’s MacBook Pro", "platform_version": "MacBookPro18,2", "os_name": "MacOSX", "os_version": "15.7.1", "ip_address": "192.0.2.254" }, "location": { "country": "CA", "region": "Ontario", "city": "Toronto", "latitude": 43.5991, "longitude": -79.4988 }, "target_user": { "uuid": "ETWZJTQCSRFPVOX74KERGHPBTU", "name": "Wendy Appleseed", "email": "wendy_appleseed@agilebits.com", "type": "user" }, "account_uuid": "4XHKKHXODJANPD6ZTBAXK4IM7E" } ] } ``` ### 3. Review the response Review the response that was returned to check that the request was successful. The example request above shows a successful `200` response, with JSON objects detailing the sign-in attempt event(s) and a cursor for continued calling of the API. See the [response schema for the `signinattempts` endpoint](/docs/events-api/reference#responses-3) for more information. If the request was successful but your 1Password account didn't contain any events within the parameters of your request, the response will still return an object with a [cursor string](/docs/events-api/pagination#cursor). For example: ```json { "cursor": "ZX8DAQETRWxhc3RpY3NlYXJjaEN1cnNvcgH_gAABBQEFTGltaXQBBAABCVN0YXJ0VGltZQH_ggABB0VuZFRpbWUB_4IAAQtTZWFyY2hBZnRlcgEEAAEKVGllQnJlYWtlcgEMAAAACv-BBQEC_4QAAAAn_4ABAgEPAQAAAA7gfNhwAAAAAP__AQ8BAAAADuB84vwAAAAA__8A", "has_more": false, "items": [] } ``` If you made a call to a different endpoint, check the [Events API reference](/docs/events-api/reference/) for the appropriate response object schema. If you see an error, learn more about [HTTP status codes and recommended actions for error messages](/docs/events-api/status-codes). ## Step 3: Connect your 1Password account to your SIEM ### Use a pre-built connector Many SIEMs already support connecting with 1Password. To use a pre-built connector, [check if your SIEM is in the list of supported applications or services](https://support.1password.com/events-reporting#step-2-connect-your-1password-account-to-your-siem). If it is, you can follow the provided link for documentation on how to connect your 1Password account. If your SIEM isn't listed, you can also check the documentation for that service for any information they might have about connecting to a 1Password account. ### Build your own integration If your SIEM doesn't have a pre-built connector, you can build your own client to send your 1Password account activity to your SIEM. Use the [Events API reference](/docs/events-api/reference/) and documentation to learn more about how the API works. To help you get started, you can refer to the [example scripts in our GitHub repository ](https://github.com/1Password/events-api-generic/) for JavaScript, Python, Ruby, Go, and PHP. Learn more about [how to use the example scripts](/docs/events-api/generic-scripts/). ## Learn more - [1Password Events API reference](/docs/events-api/reference/) - [About the 1Password Events API](/docs/events-api/introduction/) - [1Password Events API generic scripts](/docs/events-api/generic-scripts/) - [GitHub repository of example scripts ](https://github.com/1Password/events-api-generic/) --- ## About the 1Password Events API The 1Password Events API is a REST-style API that follows the [OpenAPI 3.0 Specifications](https://spec.openapis.org/oas/latest.html). All communication between clients and servers are over HTTPS. You can use your preferred language and tools for testing and implementing the Events API. The examples in the [API reference](/docs/events-api/reference/) use [curl ](https://curl.se/) on the command line to demonstrate example requests. You can replace the values in any request with your own to receive information about events in your 1Password account. The API can access data from the last 120 days. If you need to access data from more than 120 days ago, you can [use the audit log in your 1Password account](https://support.1password.com/activity-log/). ## Requirements Before you can use the 1Password Events API, you'll need to: - [Sign up for 1Password Business](https://1password.com/pricing/password-manager). - [Set up an Events Reporting integration](/docs/events-api/get-started) in your 1Password account. - [Create a bearer token](/docs/events-api/authorization#step-1-get-a-bearer-token) and select the event features it can access. --- ## Item usage actions You can use the [1Password Events API](/docs/events-api/reference/) to send your 1Password account activity to your security information and event management (SIEM) system, including item usage. [ItemUsage objects](/docs/events-api/reference#post-apiv2itemusages) contain actions, which describe how an item was used. :::warning[caution] Actions are only captured from client apps using 1Password 8.4.0 or later. Item usage activity is only sent when client apps sync to the 1Password server. Not all item usage triggers a sync, so there may be delays before actions are received. ::: ## Item usage action values Possible values for `action` include: - `enter-item-edit-mode` - `export` - `fill` - `other` - `reveal` - `secure-copy` - `select-sso-provider` - `server-create` - `server-fetch` - `server-update` - `share` The behaviors that trigger each type of action are grouped below by 1Password client type. ### enter-item-edit-mode Client Behavior 1Password apps Add an item to Favorites.Edit an item. Usage is recorded upon selecting Edit, whether or not the item is modified. ### export Client Behavior 1Password apps Download a file.Export 1Password account data as a 1PUX or CSV file. Usage is recorded for every exported item. ### fill Client Behavior 1Password apps Fill an item by selecting: <section> "Open and fill" "Type in window" (Windows only) </section> 1Password in the browser Fill an item by selecting: <section> Autofill Auto-Type (Windows only) Open & Fill An item from the inline menu in a form field </section> ### other Item usage actions are only captured from devices using 1Password 8.4.0 or later. The `other` value indicates the action was performed using an earlier version of 1Password and is unknown. Client Behavior 1Password apps Action is unknown. ### reveal Client Behavior 1Password apps Preview a file.Reveal a password.Show a password in large type. 1Password in the browser Reveal a password.Show a password in large type. ### secure-copy Client Behavior 1Password apps Copy an item field.Copy an item's password history. 1Password in the browser Copy an item field.Copy an item in JSON format. ### select-sso-provider Client Behavior 1Password in the browser Sign in to a site using a sign-in provider. ### server-create The `server` prefix indicates that the action occurred on the server rather than in the client app. Client Behavior 1Password apps Duplicate an item.Move an item. 1Password.com Create an item.Duplicate an item. 1Password CLI Create an item. 1Password Connect server Create an item. ### server-fetch The `server` prefix indicates that the action occurred on the server rather than the client app. `server-fetch` is a special kind of action type that isn't used by most clients. It's only used when the client reporting the usage is a web server, like 1Password Connect server. Client Behavior 1Password apps Download a file.Preview a file. 1Password.com Open an item. 1Password CLI Open an item. 1Password Connect server Get all of an item's files.Get the contents of a file.Get the details of a file.Get the details of an item. ### server-update The `server` prefix indicates that the action occurred on the server rather than the client app. Client Behavior 1Password apps Add an item to Favorites.Archive an item.Delete an item.Edit an item.Move an item.Restore an item. 1Password in the browser Add an item to Favorites. 1Password.com Add an item to Favorites.Archive an item.Delete an item.Edit an item.Restore an item. 1Password CLI Archive an item.Delete an item.Edit an item. 1Password Connect server Delete an item.Edit an item.Replace an item. ### share Client Behavior 1Password apps Copy an item in JSON format.Duplicate an item.Move an item.Share a link to an item. 1Password.com Share a link to an item. ## Learn more - [Get started with 1Password Events Reporting](https://support.1password.com/events-reporting/) - [1Password Events API reference](/docs/events-api/reference/) - [Get started with 1Password Events Reporting and Elastic](https://support.1password.com/events-reporting-elastic/) - [Get started with 1Password Events Reporting and Splunk](https://support.1password.com/events-reporting-splunk/) - [1Password command-line tool: Full documentation](/docs/cli/reference/) --- ## 1Password Events API The 1Password Events API allows you to retrieve information about activity in your 1Password Business account and send it to your security information and event management (SIEM) system. With the Events API, you can keep track of: - Actions team members take in the account, such as changes to vaults, groups, users, and more. - How and when items in shared vaults are used, like when an item is viewed, copied, or edited. - Attempts to sign in to the 1Password account, including when and where a user signed in to the account, and detailed information about failed sign in attempts. ## Quick start To create an Events Reporting integration to connect your 1Password Business account with your SIEM, [start here](/docs/events-api/get-started). After you set up the integration in your 1Password account, read more [about the 1Password Events API](/docs/events-api/introduction) and look at some [example scripts](/docs/events-api/generic-scripts). ## Reference documentation - Read the full [1Password Events API reference](/docs/events-api/reference/). - Learn about [audit events](/docs/events-api/audit-events/). - Learn about [item usage actions](/docs/events-api/item-usage-actions). - Track [version changes](/docs/events-api/changelog/). --- ## Pagination The Events API uses cursor-based pagination, which is useful for working with large datasets. In response to each request, the API returns a unique ID (cursor) that indicates where you left off retrieving data. On the next call, you can provide that cursor to continue fetching events starting from the next point in the dataset so no records are missed. There are two types of cursors used in calls to the API: a [reset cursor](#reset-cursor) and a [cursor](#cursor) (also called a continuing cursor). ## Reset cursor A reset cursor is used for the first request you make to the API to create a new point from which to start fetching data. You can also use a reset cursor any time you need to reset the parameters of your cursor – such as the number of records to return with each request – or go back to an earlier point in the records. For the first POST request you make to the API, you must include a `ResetCursor` object with an optional start time, end time, and limit parameters in the request body. The return will include a `cursor` in the response body that can be used in the next call made to the API. If no parameters are provided, the API will use the default values indicated in the schema. For example: **Example reset cursor request:** ```json { "limit": 100, "start_time": "2023-03-15T16:32:50-03:00", "end_time": "2023-03-15T17:32:50-03:00" } ``` **ResetCursor object schema:** Name Type Description `limit` (optional) number The number of events to return in a single request. Specify a limit from 1 to 1000. If not specified, `limit` will default to 100. To return additional events, use the cursor position for subsequent requests. `start_time` (optional) string The date and time to start retrieving events. Uses the RFC 3339 standard. If not specified, `start_time` will default to one hour before specified `end_time`. If no `end_time` is specified, `start_time` will default to one hour ago. `end_time` (optional) string The date and time to stop retrieving events. Uses the RFC 3339 standard. ## Cursor For continued calling of the API, include the `cursor` from the previous response in the request body of your next call to the API, instead of the `ResetCursor` object. This will start fetching data from the last indicated position to avoid missing any data. **Example cursor:** ```json { "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" } ``` **Cursor object schema:** Name Type Description `cursor` string Cursor to fetch more data, if available, or continue the polling process. Use the cursor returned in the response body of your previous to the endpoint. For example: `aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK`. The 1Password Events API apps for [Splunk](http://support.1password.com/events-reporting-splunk/) and [Elastic](http://support.1password.com/events-reporting-elastic/) will store the `cursor` position for future requests. --- ## Rate limits The Events API has the following limits: - 600 requests per minute - 30,000 requests per hour Exceeding these limits will return the following error: ``` 429 Too many requests ``` --- ## 1Password Events API reference :::tip This API reference documents the latest version of the [1Password Events API specifications (1.4.1)](https://i.1password.com/media/1password-events-reporting/1password-events-api_1.4.1.yaml). Learn more about [API versions](/docs/events-api/endpoints#endpoint-versions). ::: ## GET /api/v2/auth/introspect ``` base_url/api/v2/auth/introspect ``` A GET call to this endpoint returns a list of events (features) a bearer token is authorized to access, including one or more of: audit events, item usage, and sign-in attempts. It also returns the UUID of the account where the token was issued. ### Parameters No parameters. ### Requests Use the full URL of the `introspect` endpoint with your [bearer token](/docs/events-api/authorization/) and the required [request headers](/docs/events-api/request-headers/). A GET request doesn't include a body, so the content type header isn't needed. For example: ```shell curl --request GET \ --url base_url/api/v2/auth/introspect \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' ``` ### Responses <dl> <dt>200</dt> <dd>Returns an `Introspection` object</dd> <dt>400</dt> <dd>Bad request</dd> <dt>401</dt> <dd>Unauthorized access</dd> <dt>500</dt> <dd>Internal server error</dd> </dl> A successful `200` response returns an `Introspection` object with information about the token. **Example introspection response:** ```json { "uuid": "OK41XEGLRTH4YKO5YRTCPNX3IU", "issued_at": "2023-03-05T16:32:50-03:00", "features": [ "auditevents", "itemusages", "signinattempts" ], "account_uuid": "M4E2SWNZAZFTRGQGDNS2E5A4MU" } ``` **IntrospectionV2 object schema:** Name Type Description `uuid` string The UUID of the Events Reporting integration. `issued_at` string The date and time the token was issued. Uses the RFC 3339 standard. `features` array of strings A list of event features the integration has access to. Possible values are one or more of: <section> `auditevents` `itemusages` `signinattempts` </section> `account_uuid` string The UUID of the account where the bearer token was issued. ## POST /api/v2/auditevents ``` base_url/api/v2/auditevents ``` A POST call to this endpoint returns information about actions performed by team members within a 1Password account. Events include when an action was performed and by whom, along with details about the type and object of the action and any other information about the activity. MSP accounts include additional information about the actor's account and type. Learn more about [audit events](/docs/events-api/audit-events/). This endpoint requires a [bearer token](/docs/events-api/authorization/) with the `auditevents` feature. You can make an [introspection call](#get-apiv2authintrospect) to the API to verify if your token is authorized to access audit events. ### Parameters No parameters. ### Requests Use the full URL of the `auditevents` endpoint with your [bearer token](/docs/events-api/authorization/) and the required [request headers](/docs/events-api/request-headers/). You must include a [ResetCursor](/docs/events-api/pagination#reset-cursor) object or the [cursor](/docs/events-api/pagination#cursor) from a previous response in the request body. **Example audit events request with a reset cursor:** ```shell curl --request POST \ --url base_url/api/v2/auditevents \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "limit": 100, "start_time": "2023-03-15T16:32:50-03:00" }' ``` **Example audit events request with a continuing cursor:** ```shell curl --request POST \ --url base_url/api/v2/auditevents \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" }' ``` ### Responses A successful `200` response returns an `AuditEventItemsV2` object wrapping cursor properties and an array of `AuditEventV2` objects. The included cursor can be used to fetch more data or continue the polling process. <dl> <dt>200</dt> <dd>Returns an `AuditEventItemsV2` object</dd> <dt>400</dt> <dd>Bad request</dd> <dt>401</dt> <dd>Unauthorized access</dd> <dt>500</dt> <dd>Internal server error</dd> </dl> **Example audit event response:** ```json { "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK", "has_more": true, "items": [ { "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E", "timestamp": "2023-03-15T16:33:50-03:00", "actor_uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V", "actor_details": { "uuid:": "4HCGRGYCTRQFBMGVEGTABYDU2V", "name": "Jeff Shiner", "email": "jeff_shiner@agilebits.com" }, "action": "join", "object_type": "gm", "object_uuid": "pf8soyakgngrphytsyjed4ae3u", "aux_id": 9277034, "aux_uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY", "aux_details": { "uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY", "name": "Wendy Appleseed", "email": "wendy_appleseed@agilebits.com" }, "aux_info": "R", "session": { "uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM", "login_time": "2023-03-15T16:33:50-03:00", "device_uuid": "lc5fqgbrcm4plajd8mwncv2b3u", "ip": "192.0.2.254" }, "location": { "country": "Canada", "region": "Ontario", "city": "Toronto", "latitude": 43.5991, "longitude": -79.4988 } } ] } ``` **AuditEventV2 object schemas:** #### AuditEventItemsV2 object schema Name Type Description `cursor` string Cursor to return more event data or to continue polling. `has_more` boolean Whether there's more data to be returned using the cursor. If the value is `true`, there may be more events. If the value is `false`, there are no more events. `items` array An array of AuditEventV2 objects. ##### AuditEventV2 object schema Name Type Description `uuid` string The UUID of the action event. `timestamp` string The date and time when the action was performed. Uses the RFC 3339 standard. `actor_uuid` string The UUID of the user who performed the action. `actor_details` object A user object. `actor_type` string The type of user who performed the action (internal or external). Possible values are: <section> `user` `external_user` (MSP accounts only) </section> `actor_account_uuid` string The UUID of the account the user belongs to. `account_uuid` string The UUID of the account where the action was performed. `action` string The type of action that was performed. Possible values are: <section> `"activate"` `"addgsso"` `"begin"` `"beginr"` `"cancel"` `"cancelr"` `"changeks"` `"changeks"` `"changela"` `"changemp"` `"changenm"` `"changesk"` `"chngasso"` `"chngdsso"` `"chngpsso"` `"complete"` `"completr"` `"convert"` `"create"` `"dealldev"` `"delete"` `"delgsso"` `"delshare"` `"deolddev"` `"detchild"` `"disblduo"` `"disblmfa"` `"disblsso"` `"dlgsess"` `"dvrfydmn"` `"enblduo"` `"enblmfa"` `"enblsso"` `"expire"` `"export"` `"grant"` `"hide"` `"join"` `"launchi"` `"leave"` `"musercom"` `"muserdec"` `"patch"` `"propose"` `"provsn"` `"prsndall"` `"purge"` `"rdmchild"` `"reactive"` `"reauth"` `"replace"` `"replace"` `"resendts"` `"revoke"` `"role"` `"sdvcsso"` `"sendpkg"` `"sendts"` `"share"` `"ssotknv"` `"suspend"` `"tdvcsso"` `"trename"` `"trevoke"` `"trvlaway"` `"trvlback"` `"tverify"` `"uisas"` `"unhide"` `"unknown"` `"unlink"` `"updatduo"` `"update"` `"updatea"` `"updatfw"` `"updatmfa"` `"upguest"` `"uvrfydmn"` `"verify"` `"view"` `"vrfydmn"` </section> Learn about audit event actions. `object_type` string The type of object the action was performed on. Possible values are: <section> `"account"` `"card"` `"cred"` `"device"` `"dlgdsess"` `"ec"` `"famchild"` `"file"` `"gm"` `"group"` `"gva"` `"invite"` `"item"` `"itemhist"` `"items"` `"miguser"` `"mngdacc"` `"pm"` `"report"` `"sa"` `"satoken"` `"slackapp"` `"sso"` `"ssotkn"` `"sub"` `"template"` `"user"` `"uva"` `"vault"` `"vaultkey"` </section> Learn about audit event objects. `object_uuid` string The unique identifier for the object the action was performed on. `object_details` object An object details object. Returned if the object is a user. `aux_id` integer The identifier for someone or something that provides additional information about the activity. For example, the ID of a device that a user adds or removes from an account. `aux_uuid` string The unique identifier for someone or something that provides additional information about the activity. For example, the UUID of a team member who joins or leaves a group in an account. `aux_details` object An aux details object. Returned if the aux details relate to a user. `aux_info` string Additional information about the activity. `session` object A session object. `location` object A location object that contains details about the geolocation of the client based on the client's IP address at the time the event was performed. ###### UserV2 object schema Name Type Description `uuid` string The UUID of the user who performed the action. `name` string The name of the user who performed the action. `email` string The email address of the user who performed the action. `user_type`(MSP accounts only) string The type of user who performed the action (internal or external). Possible values are: <section> `user` `external_user` </section> `user_account_uuid`(MSP accounts only) string The UUID of the user's account. ###### Object details object schema Name Type Description `uuid` string The UUID of the user who is the object of the action. `name` string The name of the user who is the object of the action. `email` string The email address of the user who is the object of the action. ###### Aux details object schema Name Type Description `uuid` string The UUID of the user related to the additional information about the activity. For example, the user who was added to or removed from the account or vault or whom created or deleted the device. `name` string The name of the user related to the additional information about the activity. `email` string The email address of the user related to the additional information about the activity. ###### Session object schema Name Type Description `uuid` string The UUID of the session. `login_time` string The date and time the client signed in and started the session. Uses the RFC 3339 standard. `device_uuid` string The UUID of the device signed in to the session. `ip` string The IP address used for the session. ###### Location object schema Name Type Description `country` string The country where the action was performed. `region` string The region where the action was performed. `city` string The city where the action was performed. `longitude` number A coordinate that specifies the longitudinal location for where the action was performed. `latitude` number A coordinate that specifies the latitudinal location for where the action was performed. ## POST /api/v2/itemusages ``` base_url/api/v2/itemusages ``` A POST call to this endpoint returns information about items in shared vaults that have been modified, accessed, or used. Events include the name and IP address of the user who accessed the item, when the item was accessed, and the vault where the item is stored. Learn more about [item usage actions](/docs/events-api/item-usage-actions/). This endpoint requires a [bearer token](/docs/events-api/authorization/) with the `itemusages` feature. You can make an [introspection call](#get-apiv2authintrospect) to the API to verify if your token is authorized to access sign-in events. ### Parameters No parameters. ### Requests Use the full URL of the `itemusages` endpoint with your [bearer token](/docs/events-api/authorization/) and the required [request headers](/docs/events-api/request-headers/). You must include a [ResetCursor](/docs/events-api/pagination#reset-cursor) object or the [cursor](/docs/events-api/pagination#cursor) from a previous response in the request body. **Example item usage request with a reset cursor:** ```shell curl --request POST \ --url base_url/api/v2/itemusages \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "limit": 100, "start_time": "2023-03-15T16:32:50-03:00" }' ``` **Example item usage request with a continuing cursor:** ```shell curl --request POST \ --url base_url/api/v2/itemusages \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" }' ``` ### Responses <dl> <dt>200</dt> <dd>Returns an `ItemUsageV2` response object</dd> <dt>400</dt> <dd>Bad request</dd> <dt>401</dt> <dd>Unauthorized access</dd> <dt>500</dt> <dd>Internal server error</dd> </dl> A successful `200` response returns an `ItemUsageItemsV2` object wrapping cursor properties and an array of `ItemUsageV2` objects. The included cursor can be used to fetch more data or continue the polling process. The response also includes a cursor to continue fetching more data or to use the next time you make a request. **Example item usage response:** ```json { "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK", "has_more": true, "items": [ { "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E", "timestamp": "2023-03-15T16:33:50-03:00", "used_version": 0, "vault_uuid": "VZSYVT2LGHTBWBQGUJAIZVRABM", "item_uuid": "SDGD3I4AJYO6RMHRK8DYVNFIDZ", "user": { "uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V", "name": "Wendy Appleseed", "email": "wendy_appleseed@agilebits.com" }, "client": { "app_name": "1Password Browser", "app_version": "20240", "platform_name": "Chrome", "platform_version": "string", "os_name": "MacOSX", "os_version": "13.2", "ip_address": "192.0.2.254" }, "location": { "country": "Canada", "region": "Ontario", "city": "Toronto", "latitude": 43.5991, "longitude": -79.4988 }, "action": "secure-copy" } ] } ``` **ItemUsageV2 object schemas:** #### ItemUsageItemsV2 object schema Name Type Description `items` array An array of ItemUsageV2 objects. `cursor` string Cursor to return more event data or to continue polling. `has_more` boolean Whether there's more data to be returned using the cursor. If the value is `true`, there may be more events. If the value is `false`, there are no more events. ##### ItemUsageV2 object schema Name Type Description `uuid` string The UUID of the event. `timestamp` string The date and time of the event. RFC 3339 standard. `used_version` integer The version of the item that was accessed. `vault_uuid` string The UUID of the vault the item is in. `item_uuid` string The UUID of the item that was accessed. `action` string Details about how the item was used. Actions are only captured from client apps using 1Password 8.4.0 or later. Possible values are: <section> `"enter-item-edit-mode"` `"export"` `"fill"` `"other"` `"reveal"` `"secure-copy"` `"select-sso-provider"` `"server-create"` `"server-fetch"` `"server-update"` `"share"` </section> Learn about item usage actions. `user` object A user object. `client` object A client object. `location` object A location object that contains details about the geolocation of the client based on the client's IP address at the time the event was performed. `account_uuid`(MSP accounts only) string The UUID of the account where the action was performed. ###### UserV2 object schema Name Type Description `uuid` string The UUID of the user that accessed the item or attempted to sign in to the account. `name` string The name of the user, hydrated at the time the event was generated. `email` string The email address of the user, hydrated at the time the event was generated. `user_type`(MSP accounts only) string The type of user who performed the action (internal or external). Possible values are: <section> `user` `external_user` </section> `user_account_uuid`(MSP accounts only) string The UUID of the user's account. ###### Client object schema Name Type Description `app_name` string The name of the 1Password app the item was accessed from. `app_version` string The version number of the app. `platform_name` string The name of the platform the item was accessed from. `platform_version` string The version of the browser or computer where 1Password is installed or the CPU of the machine where the 1Password command-line tool is installed. `os_name` string The name of the operating system the item was accessed from. `os_version` string The version of the operating system the item was accessed from. `ip_address` string The IP address the item was accessed from. ###### Location object schema {#location-object-schema-1} Name Type Description `country` string The country where the item was accessed. `region` string The region where the item was accessed. `city` string The city where the item was accessed. `longitude` number A coordinate that specifies the longitudinal location for where the item was accessed. `latitude` number A coordinate that specifies the latitudinal location for where the item was accessed. ## POST /api/v2/signinattempts ``` base_url/api/v2/signinattempts ``` A POST call to this endpoint returns information about sign-in attempts. Events include the name and IP address of the user who attempted to sign in to the account, when the attempt was made, and – for failed attempts – the cause of the failure. For MSP accounts, events also include additional information about the user's account and type. This endpoint requires a [bearer token](/docs/events-api/authorization/) with the `signinattempts` feature. You can make an [introspection call](#get-apiv2authintrospect) to the API to verify if your token is authorized to access sign-in events. ### Parameters No parameters. ### Requests Use the full URL of the `signinattempts` endpoint with your [bearer token](/docs/events-api/authorization/) and the required [request headers](/docs/events-api/request-headers/). You must include a [ResetCursor](/docs/events-api/pagination#reset-cursor) object or the [cursor](/docs/events-api/pagination#cursor) from a previous response in the request body. **Example request with a reset cursor:** ```shell curl --request POST \ --url base_url/api/v2/signinattempts \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "limit": 100, "start_time": "2023-03-15T16:32:50-03:00" }' ``` **Example request with a continuing cursor:** ```shell curl --request POST \ --url base_url/api/v2/signinattempts \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" }' ``` ### Responses <dl> <dt>200</dt> <dd>Returns a `SignInAttemptItemsV2` object</dd> <dt>400</dt> <dd>Bad request</dd> <dt>401</dt> <dd>Unauthorized access</dd> <dt>500</dt> <dd>Internal server error</dd> </dl> A successful `200` response returns a `SignInAttemptItemsV2` object wrapping cursor properties and an array of `SignInAttemptV2` objects. The included cursor can be used to fetch more data or continue the polling process. **Example sign-in attempt response:** ```json { "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK", "has_more": true, "items": [ { "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E", "session_uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM", "timestamp": "2023-03-15T16:32:50-03:00", "category": "firewall_failed", "type": "continent_blocked", "country": "France", "details": { "value": "Europe" }, "target_user": { "uuid": "IR7VJHJ36JHINBFAD7V2T5MP3E", "name": "Wendy Appleseed", "email": "wendy_appleseed@agilebits.com" }, "client": { "app_name": "1Password Browser", "app_version": "20240", "platform_name": "Chrome", "platform_version": "string", "os_name": "MacOSX", "os_version": "13.2", "ip_address": "192.0.2.254" }, "location": { "country": "Canada", "region": "Ontario", "city": "Toronto", "latitude": 43.5991, "longitude": -79.4988 } } ] } ``` **SignInAttemptsV2 object schemas:** #### SignInAttemptItemsV2 object schema Name Type Description `items` array An array of SignInAttemptsV2 objects. `cursor` string Cursor to return more event data or to continue polling. `has_more` boolean Whether there's more data to be returned using the cursor. If the value is `true`, there may be more events. If the value is `false`, there are no more events. ##### SignInAttemptsV2 object schema Name Type Description `uuid` string The UUID of the event. `session_uuid` string The UUID of the session that created the event. `timestamp` string The date and time of the sign-in attempt. Uses the RFC 3339 standard. `category` string The category of the sign-in attempt. Possible values are: <section> `"success"` `"credentials_failed"` `"mfa_failed"` `"sso_failed"` `"modern_version_failed"` `"firewall_failed"` `"firewall_reported_success"` </section> `type` string Details about the sign-in attempt. Possible values are: <section> `"all_blocked"` `"anonymous_blocked"` `"code_bad"` `"code_disabled"` `"code_timeout"` `"continent_blocked"` `"country_blocked"` `"credentials_ok"` `"duo_bad"` `"duo_disabled"` `"duo_native_bad"` `"duo_timeout"` `"federated"` `"ip_blocked"` `"mfa_missing"` `"mfa_ok"` `"modern_version_missing"` `"modern_version_old"` `"non_sso_user"` `"password_secret_bad"` `"platform_secret_bad"` `"platform_secret_disabled"` `"platform_secret_proxy"` `"service_account_sso_denied"` `"sso_user_mismatch"` `"totp_bad"` `"totp_disabled"` `"totp_timeout"` `"u2f_bad"` `"u2f_disabled"` `"u2f_timeout"` </section> `country` string The country code of the event. Uses the ISO 3166 standard. `details` object A details object that contains additional information about the sign-in attempt. `target_user` object A user object. `client` object A client object. `location` object A location object that contains details about the geolocation of the client based on the client's IP address at the time the event was performed. `account_uuid`(MSP accounts only) string The UUID of the account where the action was performed. ###### Details object schema Name Type Description `value` string The additional information about the sign-in attempt, such as any firewall rules that prevent a user from signing in. For example, in the event of a sign-in attempt blocked by firewall rules, the value is the country, continent, or IP address of the sign-in attempt. ###### UserV2 object schema {#userv2-object-schema-2} Name Type Description `uuid` string The UUID of the user that accessed the item or attempted to sign in to the account. `name` string The name of the user, hydrated at the time the event was generated. `email` string The email address of the user, hydrated at the time the event was generated. `user_type`(MSP accounts only) string The type of user who performed the action (internal or external). Possible values are: <section> `user` `external_user` </section> `user_account_uuid`(MSP accounts only) string The UUID of the user's account. ###### Client object schema {#client-object-schema-1} Name Type Description `app_name` string The name of the 1Password app the item was accessed from. `app_version` string The version number of the app. `platform_name` string The name of the platform the item was accessed from. `platform_version` string The version of the browser or computer where 1Password is installed or the CPU of the machine where the 1Password command-line tool is installed. `os_name` string The name of the operating system the item was accessed from. `os_version` string The version of the operating system the item was accessed from. `ip_address` string The IP address the item was accessed from. ###### Location object schema {#location-object-schema-2} Name Type Description `country` string The country where the sign-in attempt was made. `region` string The region where the sign-in attempt was made. `city` string The city where the sign-in attempt was made. `longitude` number A coordinate that specifies the longitudinal location where the sign-in attempt was made. `latitude` number A coordinate that specifies the latitudinal location where the sign-in attempt was made. ## ErrorResponse object **Example error response:** ```json { status: 401, message: "Unauthorized access" } ``` **ErrorResponse object schema:** Name Type Description `status` integer The HTTP status code. `message` string A message detailing the error. --- ## Request headers Requests to the Events API must include the correct header(s): - `Authorization`: Each GET and POST request to the Events API must be [authorized with a bearer token](/docs/events-api/authorization/) scoped to access event data for that feature. You'll include your token in the authorization header. - `Content-Type`: Each POST request requires a `Content-Type` header to indicate the media type of the resource being sent in the request body. All data for the Events API is sent and received as JSON, so you'll need to specify `application/json` as the content type. GET requests don't contain a request body and therefore don't require this header. An example of a request header: ``` Authorization: Bearer YOUR_BEARER_TOKEN Content-type: application/json ``` --- ## Request methods The Events API accepts the following standard HTTP request methods: - GET requests to the [`introspect`](/docs/events-api/reference#get-apiv2authintrospect) endpoint return information about the events a bearer token has access to and the account where the token was issued. - POST requests to the [`auditevents`](/docs/events-api/reference#post-apiv2auditevents), [`itemusages`](/docs/events-api/reference#post-apiv2itemusages ), and [`signinattempts`](/docs/events-api/reference#post-apiv2signinattempts) endpoints return information about various activities in a 1Password account. Depending on which endpoint is called, the request returns one of the following: - Successful and failed attempts to sign in to a 1Password account. - Information about every use of an item stored in a shared vault in the account. - Audit events for actions performed by team members in the account. --- ## Servers and base URLs The API service ID (`events`) and the server that hosts your 1Password account form the base URL you'll use for the API endpoints. | If your account is hosted on: | Your base URL is: | |------------------------|-------------------| | `1password.com` | `https://events.1password.com` | | `ent.1password.com` | `https://events.ent.1password.com` | | `1password.ca` | `https://events.1password.ca` | | `1password.eu` | `https://events.1password.eu` | --- ## HTTP status codes Calls to the 1Password Events API may return the following HTTP status codes: | Code | Message | Description / Recommended action | | --- | --- | --- | | `200` | OK | The request was successful and the server returned a JSON object or an array of objects.Recommended action: No action is required. | | `400` | Bad Request | The server could not understand the request due to invalid syntax.Recommended action: Check the [API reference](/docs/events-api/reference/) and documentation [about the API](/docs/events-api/introduction/) to make sure your request is properly formatted. | | `401` | Unauthorized | Authentication has failed or wasn't provided.Recommended action: Check that your request includes the [`Authorization` header](/docs/events-api/request-headers/), and make sure your bearer token is valid and scoped to access the requested resource. [Learn more about authorizing API requests.](/docs/events-api/authorization/) | | `429` | Too Many Requests | The rate limit has been exceeded.Recommended action: Wait until the applicable rate-limit window (per-minute or per-hour) resets, then try again. [Learn more about Events API rate limits.](/docs/events-api/rate-limits) | | `500` | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request.Recommended action: Retry your request after a brief wait. If the issue persists, check the [1Password status page](https://status.1password.com/) to verify the Events API service is operational, or [contact 1Password Support](https://support.1password.com/contact/) for help. | --- ## 1Password Partnership API reference You can use the 1Password Partnership API to manage the provisioning and deprovisioning of third-party partner billing accounts for your customers. The API supports partner billing accounts for 1Password individual and family accounts. The Partnership API doesn't support 1Password team or business accounts. :::note To work with the 1Password Partnership API in another tool, download the API specification file: [1password-partnership-api.yml](https://i.1password.com/media/1password-partnership-api/partnership-api.yml). ::: ## Prerequisites Before you can use the API to integrate with our partner billing service, you'll need to register as a 1Password partner. Registered partners are granted access to bearer tokens to authorize requests to the API billing servers. To learn more about our partnership opportunities, visit the [1Password Partner Program website](https://1password.com/partnerships) or [contact the 1Password Partnerships team](mailto:partners@1password.com). If you're not a partner, reach out to your Customer Success Manager or the [1Password Sales team](https://1password.com/contact-us). ## Information about the API The 1Password Partnership API is a REST-style API that follows the [OpenAPI 3.0 specifications](https://spec.openapis.org/oas/v3.0.3). All communication between clients and servers is over HTTPS. You can use your preferred programming language and tools for testing and implementing the Partnership API. This reference uses [curl](https://curl.se/) on the command line to demonstrate example requests. You can replace the values in any request with your own to receive information about your customers' billing accounts. ### Request methods You can use the following standard HTTP methods to make requests to the Partnership API: - [POST](#create-a-billing-account): Create a third-party billing account for a customer through the partner billing service. - [GET](#get-billing-account-information): Get details about a customer's billing account. - [DELETE](#delete-a-billing-account): Delete a customer's third-party billing account from the partner billing service. - [PATCH](#update-a-billing-account-end-date): Update the date and time a customer's billing account is scheduled be removed from the partner billing service. Batch requests are not supported. ### Servers There are two billing servers partners can use to work with the 1Password Partnership API that provide the base URLs of the API endpoints: - **Test server** (`https://billing.b5test.eu`): Use the test server URL as the base for all requests in the test environment. You can provision and deprovision test partner billing accounts for all domains from the test server: **b5test.com**, **b5test.ca**, and **b5test.eu.** - **Production server** (`https://billing.1password.com`): Use the production server URL as the base for all requests in the production environment. You can provision and deprovision partner billing accounts for all domains from the production server: **1password.com**, **1password.ca**, and **1password.eu**. ### Endpoints Each request to the API starts with the base URL of the server environment you want to work with (test or production), followed by the path (`api/v1/partners/account`). Path parameters, indicated with curly braces (`{}`), are required where defined. For example: ```text title="Structure of an API endpoint" [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "<base_URL>" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "<path>" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "{parameters}" }] <base_URL>/<path>/{parameters} ``` Replace the base_URL and \{parameters} placeholders with the server environment you're using and any path parameters specified for the request. The path is the same for all requests. ```text title="Example API endpoint without a path parameter" [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "https://billing.b5test.eu" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "api/v1/partners/accounts" }] https://billing.b5test.eu/api/v1/partners/accounts ``` ```text title="Example API endpoint with a path parameter" [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "https://billing.1password.com" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "api/v1/partners/accounts" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "4266474b-6385-56d4-7b75-648096593064" }] https://billing.1password.com/api/v1/partners/accounts/4266474b-6385-56d4-7b75-648096593064 ``` ### Authorization When you register with the [1Password Partner Program](https://1password.com/partnerships), the Partnership team will provide you with bearer tokens you'll need to authorize your calls to the Partnership API. You'll receive separate tokens to use with [the test and production environments](#servers). Make sure to use the token that has been authorized for the environment you're working in. If you're a partner and need a new bearer token, [contact the 1Password Partnerships team](mailto:partners@1password.com). If you're not a partner, reach out to your Customer Success Manager or the [1Password Sales team](https://1password.com/contact-us) and let them know you need a new bearer token. ### Request headers Requests to the Partnership API use three types of headers: - **`Authorization`**: Each GET, POST, DELETE, and PATCH request to the Partnership API must be authorized with a [bearer token](#authorization). - **`Content-Type`**: Each POST and PATCH request requires a header to indicate the media (MIME) type of the request body. - **`Accept`**: Each GET, POST, and PATCH request to the Partnership API should include an accept header to indicate what kind of response the client can accept from the server. All data is sent and received as JSON, so make sure to specify that in the headers. ``` Authorization: Bearer YOUR_BEARER_TOKEN Content-type: application/json Accept: application/json ``` If you're a partner and need a new bearer token, [contact the 1Password Partnerships team](mailto:partners@1password.com). If you're not a partner, reach out to your Customer Success Manager or the [1Password Sales team](https://1password.com/contact-us) and let them know you need a new bearer token. ### Request bodies Request bodies (also called request payloads) contain the JSON-formatted data clients send to create (POST) or update (PATCH) resources on the servers. A request body consists of an object that may include one or more of the following fields, as indicated: - **The unique identifier (UID) for the customer's billing account.** The UID is supplied by the partner. It can be up to 200 characters long with any combination of alphanumeric characters (`A-Z`, `a-z`, `0-9`), hyphens (`-`), and periods/dots (`.`) . - **The 1Password account type.** Options are individual (`I`) or family (`F`). Team and business accounts aren't supported. - **The domain the customer can use for their new or existing 1Password account.** For the test server, options are: `b5test.com`, `b5test.ca`, or `b5test.eu`. For the production server, options are: `1password.com`, `1password.ca`, or `1password.eu`. - **The date and time the customer's billing account is scheduled to be removed.** The date cannot be in the past. Format the date, time, and optional timezone in the [ISO 8601 standard](https://www.iso.org/iso-8601-date-and-time-format.html). GET and DELETE calls don't contain request bodies. ### Activation tokens Activation tokens are used to provision customers to third-party billing by linking 1Password accounts to partner billing accounts. Make a [POST call](#create-a-billing-account) to the Partnership API to create a new partner billing account for a customer and generate their unique activation token. Append the token returned in the [POST response](#success-response) to a 1Password partnership redemption link to [create the customer's partner billing link](#create-a-link-for-customers). Then provide the customer with their link. The link will direct the customer to a promotional page where they'll be instructed to create a new 1Password account or sign in to an existing one. The billing for the customer's 1Password account will then be linked to their partner billing account. #### Create a link for customers To create a partner billing link for a customer, adjust the 1Password partnership redemption link (`https://start.[1password_domain]/partnership/redeem`) to use the desired 1Password domain. Then append a query string with the required parameters for the account type and the activation token. You can also include an optional [language parameter](#language-codes). ```text title="Structure of a partner billing link for a 1Password account" [{ "color": "bitsblue", "lineNo": 1, "substr": "[1password_domain]" }, { "color": "tangerine", "lineNo": 1, "substr": "{account_type}" }, { "color": "lagoon", "lineNo": 1, "substr": "{activation_token}" }, { "color": "dahlia", "lineNo": 1, "substr": "{language_code}" }] https://start.[1password_domain]/partnership/redeem?t={account_type}&c={activation_token}&l={language_code} ``` | Placeholder | Values | Required | | ----------- | ----------------------------- | -------- | | [1password_domain] | Possible values are `1password.com`, `1password.ca`, or `1password.eu`. | Yes | | \{account_type} | Possible values are `individual` or `family`. | Yes | | \{activation_token} | The value of the token returned in the [POST response](#success-response). For example: `4266474b-6385-56d4-7b75-648096593064`. | Yes | | \{language_code} | Optional [language code](#language-codes) values are `en`, `de`, `es`, `fr`, `it`, `ja`, `ko`, `nl`, `pt-BR`, `ru`, `zh-Hans`, or `zh-Hant`. | No | Replace the placeholders for the 1Password domain and the parameters with the appropriate values. For example: ```text title="Example partner billing link for an individual account on 1Password.eu with an optional language parameter" [{ "color": "bitsblue", "lineNo": 1, "substr": "1password.eu" }, { "color": "tangerine", "lineNo": 1, "substr": "individual" }, { "color": "lagoon", "lineNo": 1, "substr": "4266474b-6385-56d4-7b75-648096593064" }, { "color": "dahlia", "lineNo": 1, "substr": "de", "fromIndex": 45 }] https://start.1password.eu/partnership/redeem?t=individual&c=4266474b-6385-56d4-7b75-648096593064&l=de ``` ```text title="Example partner billing link for a family account on 1Password.com with an optional language parameter" [{ "color": "bitsblue", "lineNo": 1, "substr": "1password.com" }, { "color": "tangerine", "lineNo": 1, "substr": "family" }, { "color": "lagoon", "lineNo": 1, "substr": "4266474b-6385-56d4-7b75-648096593064" }, { "color": "dahlia", "lineNo": 1, "substr": "en" }] https://start.1password.com/partnership/redeem?t=family&c=4266474b-6385-56d4-7b75-648096593064&l=en ``` If you're not sure which link(s) you need to create, [contact the 1Password Partnerships team](mailto:partners@1password.com) for help. :::warning[caution] For customers with existing 1Password accounts, partner billing links will only work if their 1Password account type and domain are the same as the ones specified in the [POST request](#request). Customers can [contact 1Password Support](https://support.1password.com/contact/) if they need help to change their existing [account type](https://support.1password.com/change-account-type/) or [region](https://support.1password.com/regions#change-your-region). ::: #### Alternate partner billing link options **Learn more about alternate link options.** The Partnership API also supports some alternate options for partner billing links. Depending on the details of your partnership, you might prefer to create links for: - [A new 1Password account only](#create-a-link-for-a-new-1password-account-only) - [An existing 1Password account only](#create-a-link-for-an-existing-1password-account-only) If you provide a customer with one of these links, they'll only be able to use it to link their partner billing account to either a new account or an existing account, respectively. You can also create one link of each type and provide your customers with both so they can choose the option they need. However, creating a [single link](#create-a-link-for-customers) that allows for both options may be a better solution. ##### Create a link for a new 1Password account only To create a partner billing link for a customer to use with a new 1Password account only, adjust the 1Password sign-up link (`https://start.[1password_domain]/sign-up/[account_type]`) to use the desired 1Password domain and account type. Then append a query string with the required activation token parameter. You can also include an optional [language parameter](#language-codes). For example: ```text title="Structure of a partner billing link for a new 1Password account" [{ "color": "bitsblue", "lineNo": 1, "substr": "[1password_domain]" }, { "color": "tangerine", "lineNo": 1, "substr": "[account_type]" }, { "color": "lagoon", "lineNo": 1, "substr": "{activation_token}" }, { "color": "dahlia", "lineNo": 1, "substr": "{language_code}" }] https://start.[1password_domain]/sign-up/[account_type]?c={activation_token}&l={language_code} ``` Replace the [placeholders](#placeholder-reference) for the 1Password domain, account type, and the parameters with the appropriate values. For example: ```text title="Example partner billing link for a new individual account on 1Password.eu with an optional language parameter" [{ "color": "bitsblue", "lineNo": 1, "substr": "1password.eu" }, { "color": "tangerine", "lineNo": 1, "substr": "individual" }, { "color": "lagoon", "lineNo": 1, "substr": "4266474b-6385-56d4-7b75-648096593064" }, { "color": "dahlia", "lineNo": 1, "substr": "de" }] https://start.1password.eu/sign-up/individual?c=4266474b-6385-56d4-7b75-648096593064&l=de ``` ```text title="Example partner billing link for a new family account on 1Password.com with an optional language parameter" [{ "color": "bitsblue", "lineNo": 1, "substr": "1password.com" }, { "color": "tangerine", "lineNo": 1, "substr": "family" }, { "color": "lagoon", "lineNo": 1, "substr": "4266474b-6385-56d4-7b75-648096593064" }, { "color": "dahlia", "lineNo": 1, "substr": "en" }] https://start.1password.com/sign-up/family?c=4266474b-6385-56d4-7b75-648096593064&l=en ``` ##### Create a link for an existing 1Password account only To create a partner billing link for a customer to use with an existing 1Password account only, adjust the 1Password account sign-in link (`https://my.[1password_domain]/partnership/link`) to use the desired 1Password domain. Then append a query string with the required activation token parameter. You can also include an optional [language parameter](#language-codes). For example: ```text title="Structure of a partner billing link for an existing 1Password account" [{ "color": "bitsblue", "lineNo": 1, "substr": "[1password_domain]" }, { "color": "lagoon", "lineNo": 1, "substr": "{activation_token}" }, { "color": "dahlia", "lineNo": 1, "substr": "{language_code}" }] https://my.[1password_domain]/partnership/link?c={activation_token}&l={language_code} ``` Replace the [placeholders](#placeholder-reference) for the 1Password domain and the parameters with the appropriate values. For example: ```text title="Example partner billing link for an existing account on 1Password.com with an optional language parameter" [{ "badge": 1, "color": "bitsblue", "lineNo": 1, "substr": "1password.com" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "4266474b-6385-56d4-7b75-648096593064" }, { "badge": 3, "color": "dahlia", "lineNo": 1, "substr": "en" }] https://my.1password.com/partnership/link?c=4266474b-6385-56d4-7b75-648096593064&l=en ``` This link doesn't include an account type because it directs the customer to sign in to the 1Password account they already have. ##### Placeholder reference | Placeholder | Values | Required | | ----------- | ----------------------------- | -------- | | [1password_domain] | Possible values are `1password.com`, `1password.ca`, or `1password.eu`. | Yes | | [account_type] | The account type is only used with links to [create a new 1Password account](#create-a-link-for-a-new-1password-account-only). Possible values are `individual` or `family`. | Yes For new accounts only | | \{activation_token} | The value of the token returned in the [POST response](#success-response). For example: `4266474b-6385-56d4-7b75-648096593064`. | Yes | | \{language_code} | Optional [language code](#language-codes) values are `en`, `de`, `es`, `fr`, `it`, `ja`, `ko`, `nl`, `pt-BR`, `ru`, `zh-Hans`, or `zh-Hant`. | No | #### Language code parameters {#language-codes} **Learn more about optional language code parameters.** Language codes are an optional parameter that can be added to a [partner billing link](#create-a-link-for-customers) to take the customer to the appropriate landing page for that language. Customers will be directed to the default landing page (English) if no language parameter is included. The following language codes can be used with the language parameter: | Language | Code | | -------- | ---- | | English | `en` | | Deutsch | `de` | | Español | `es` | | Français | `fr` | | Italiano | `it` | | 日本語 | `ja` | | Language | Code | | -------- | ---- | | 한국어 | `ko` | | Nederlands | `nl` | | Português | `pt-BR` | | Русский | `ru` | | 简体中文 | `zh-Hans` | | 繁體中文 | `zh-Hant` | ## Create a billing account ``` POST <base_URL>/api/v1/partners/accounts ``` A POST call creates a new third-party billing account for a customer through the partner billing service and returns the [activation token](#activation-tokens) you'll use to create a partner billing link for the customer to complete provisioning. ### Path parameters No path parameters. ### Request Use the endpoint URL with your [bearer token](#authorization) and the required [request headers](#request-headers). Include an object as a [request body](#request-bodies) that contains: - The customer's account UID. - The eligible 1Password account type. - The domain the customer can use for their new or existing 1Password account. - (Optional) The date and time you want to remove the customer's account from the partner billing service. This value cannot be in the past. You can also update this field with [a PATCH request](#update-a-billing-account-end-date). **Example request:** ```shell {7,8,9,10} curl --request POST \ --url https://billing.1password.com/api/v1/partners/accounts \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --data '{ "customer_account_uid": "4266474b-6385-56d4-7b75-648096593064", "account_type": "F", "domain": "1password.com", "ends_at": "2024-08-31T13:00:00-05:00" }' ``` **Request object schema:** Name Type Description `customer_account_uid`Required string The unique identifier (UID) for the customer's billing account. The UID can be up to 80 characters long with any combination of alphanumeric characters and hyphens. `account_type`Required string The type of 1Password account you want to provision for the customer: `I` for individual account or `F` for family account. Team and business accounts aren't supported. `domain`Required string The domain for the new or existing 1Password account the customer can use with the partner billing service. For the test server: `b5test.com`, `b5test.ca`, or `b5test.eu`. For the production server: `1password.com`, `1password.ca`, or `1password.eu`. `ends_at` string The date and time the customer's billing account is scheduled to be removed from the partner billing service. Uses the format defined by RFC 3339. ### Success response A `201` response returns an Account object containing the unique [activation token](#activation-tokens) that's used to link the customer's 1Password account with their partner billing account. **Example response:** ```json {4} { "customer_account_uid": "4266474b-6385-56d4-7b75-648096593064", "account_type": "F", "activation_token": "PNS-D5A75BT2", "domain": "1password.com", "status": "entitled", "deployed_members": 0, "created_at": "2023-08-24T04:19:44Z", "updated_at": "2023-09-15T15:58:22Z", "ends_at": "2024-08-31T18:00:00Z" } ``` **Response object schema:** Name Type Description `customer_account_uid` string The unique identifier (UID) for the customer's billing account. The UID can be up to 80 characters long with any combination of alphanumeric characters and hyphens. `account_type` string The type of 1Password account you provisioned for the customer: `I` for individual account or `F` for family account. `activation_token` string The activation token you'll use to create a link that connects the customer's new or existing 1Password account to their partner billing account (for example, `https://start.[1password_domain]/partnership/redeem?t=[account_type]&c=[activation_token]&l=[language_code]`). Tokens can only be used with a 1Password individual or family account. Team and business accounts aren't supported. `domain` string The domain for the new or existing 1Password account the customer can use with the partner billing service. For the test server: `b5test.com`, `b5test.ca`, or `b5test.eu`. For the production server: `1password.com`, `1password.ca`, or `1password.eu`. `status` string The status of the customer billing account that was provisioned. Possible values are one of: <section> `entitled` Provisioning has been initiated, but the customer hasn't used their partner billing link with a new or existing 1Password account. `provisioned` The customer has used their partner billing link with a new or existing 1Password account, and their third-party billing account has been provisioned. </section> The expected value for the POST request is `entitled`. `deployed_members` integer The number of provisioned users in the 1Password account. The expected value returned for a POST request is `0`. `created_at` string The date and time the customer's billing account was created. Uses the ISO 8601 standard. `updated_at` string The date and time the billing account was last updated. Uses the ISO 8601 standard. This field is updated when there are account status changes. The expected value returned for a POST request is the same as the value of the `created_at` property. `ends_at` string The date and time the customer's billing account is scheduled to be removed from the partner billing service. Uses the ISO 8601 standard. If a date and time haven't been specified, the expected value is `null`. ### Error responses <details className="slim-details"> **`400` Returned on bad requests.** **Example error:** ```json { "code": 400, "error": "bad_request", "description": "Account type B is not supported." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine-parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`403` Returned when the authorization header is missing from the request body or an invalid token is specified.** **Example error:** ```json { "code": 403, "error": "forbidden", "description": "Invalid auth token." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine-parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`404` Returned when a resource or dependency of a resource isn't found.** **Example error:** ```json { "code": 404, "error": "not_found", "description": "Domain not found." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine-parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`500` Returned on unexpected errors.** **Example error:** ```json { "code": 500, "error": "internal_server_error", "description": "Internal server error" } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. ## Get billing account information ``` GET <base_URL>/api/v1/partners/accounts/{customer_account_uid} ``` A GET call retrieves information about a customer's billing account. Make sure to include the customer's account UID as a path parameter. ### Path Parameters Parameter Type Description `customer_account_uid`Required string The unique ID of the customer's billing account. ### Request Use the endpoint URL with your [bearer token](#authorization) and the required [request headers](#request-headers) to request a customer's billing account information. The GET request doesn't include a body, so the `Content-type` header isn't used. **Example request:** ```shell curl --request GET \ --url https://billing.1password.com/api/v1/partners/accounts/{customer_account_uid} \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ --header 'Accept: application/json' ``` ### Success response A `200` response returns an Account object that provides information about the customer's third-party billing account. **Example response:** ```json { "customer_account_uid": "4266474b-6385-56d4-7b75-648096593064", "account_type": "F", "activation_token": "PNS-D5A75BT2", "domain": "1password.com", "status": "provisioned", "deployed_members": 1, "created_at": "2023-08-24T04:19:44Z", "updated_at": "2023-09-15T15:58:22Z", "ends_at": "2024-08-31T18:00:00Z" } ``` **Response object schema:** Name Type Description `customer_account_uid` string The unique identifier (UID) for the customer's billing account. The UID can be up to 80 characters long with any combination of alphanumeric characters and hyphens. `account_type` string The type of 1Password account you provisioned for the customer: `I` for individual account or `F` for family account. `activation_token` string The activation token you'll use to create a link that connects the customer's new or existing 1Password account to their partner billing account (for example, `https://start.[1password_domain]/partnership/redeem?t=[account_type]&c=[activation_token]&l=[language_code]`). Tokens can only be used with a 1Password individual or family account. Team and business accounts aren't supported. `domain` string The domain for the new or existing 1Password account the customer can use with the partner billing service. For the test server: `b5test.com`, `b5test.ca`, or `b5test.eu`. For the production server: `1password.com`, `1password.ca`, or `1password.eu`. `status` string The status of the customer billing account that was provisioned. Possible values are one of: <section> `entitled` Provisioning has been initiated, but the customer hasn't used their partner billing link with a new or existing 1Password account. `provisioned` The customer has used their partner billing link with a new or existing 1Password account, and their third-party billing account has been provisioned. </section> `deployed_members` integer The number of provisioned users in the 1Password account. `created_at` string The date and time the customer's billing account was created. Uses the ISO 8601 standard. `updated_at` string The date and time the customer's billing account was last updated. Uses the ISO 8601 standard. This field updates when there are account status changes. `ends_at` string The date and time the customer's billing account is scheduled to be removed from the partner billing service. Uses the ISO 8601 standard. If a date and time haven't been specified, the expected value is `null`. ### Error responses <details className="slim-details"> **`403` Returned when the authorization header is missing or an invalid token is specified.** **Example error:** ```json { "code": 403, "error": "forbidden", "description": "Invalid auth token." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`404` Returned when a resource or dependency of a resource isn't found.** **Example error:** ```json { "code": 404, "error": "not_found", "description": "Failed to find the requested account." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`410` Returned when a resource has been removed.** **Example error:** ```json { "code": 410, "error": "gone", "description": "The requested account is gone." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`500` Returned on unexpected errors.** **Example error:** ```json { "code": 500, "error": "internal_server_error", "description": "Internal server error" } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. ## Delete a billing account ``` DELETE <base_URL>/api/v1/partners/accounts/{customer_account_uid} ``` A DELETE call removes a customer's third-party billing account from the partner billing service. Make sure to include the customer's account UID as a path parameter. ### Path Parameters Parameter Type Description `customer_account_uid`Required string The unique ID of the customer billing account to remove. ### Request Use the endpoint URL with your [bearer token](#authorization) for the required [request header](#request-headers) to remove a customer's billing account. The DELETE request and subsequent response don't include a body, so the `Content-type` and `Accept` headers aren't used. **Example request:** ```shell curl --request DELETE \ --url https://billing.1password.com/api/v1/partners/accounts/{customer_account_uid} \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ ``` ### Success response A `204` response is returned on successful deactivation and removal of a customer billing account. A GET request will no longer return account information for the customer account UID because the billing account has been deleted. ### Error responses <details className="slim-details"> **`403` Returned when the authorization header is missing or an invalid token is specified.** **Example error:** ```json { "code": 403, "error": "forbidden", "description": "Invalid auth token." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`404` Returned when a resource or dependency of a resource isn't found.** **Example value:** ```json { "code": 404, "error": "not_found", "description": "Failed to find the requested account." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`500` Returned on unexpected errors.** **Example error:** ```json { "code": 500, "error": "internal_server_error", "description": "Internal server error" } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. ## Update a billing account end date ``` PATCH <base_URL>/api/v1/partners/accounts/{customer_account_uid} ``` A PATCH call lets you add, edit, or remove the end date for a customer's billing account. Make sure to include the customer's account UID as a path parameter. ### Path Parameters Parameter Type Description `customer_account_uid`Required string The unique ID of the customer's billing account. ### Request Use the endpoint URL with your [bearer token](#authorization) and the required [request headers](#request-headers). Include an object as a [request body](#request-bodies) that contains the `ends_at` field. To add or update the date and time a customer's billing account is scheduled to be removed from the partnership billing service, include a new date and time as the `ends_at` value, in the format defined by RFC 3339. To remove the end date and time from a customer's billing account, use an empty string (`""`) or `null` as the value. **Example request:** ```shell {6} curl --request PATCH \ --url https://billing.1password.com/api/v1/partners/accounts/{customer_account_uid} \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ --header 'Accept: application/json' \ --data '{ "ends_at": "2024-08-31T13:00:00-05:00" }' ``` **Request object schema:** Name Type Description `ends_at`Required string The date and time the customer's billing account is scheduled to be removed from the partner billing service. Uses the format defined by RFC 3339. If you want to remove the end date from an account, use an empty string (`""`) or `null` as the value. ### Success response A `200` response returns an Account object that provides information about the customer's third-party billing account, including the end date that has been added, edited, or removed from the billing account. **Example response:** ```json {10} { "customer_account_uid": "4266474b-6385-56d4-7b75-648096593064", "account_type": "F", "activation_token": "PNS-D5A75BT2", "domain": "1password.com", "status": "provisioned", "deployed_members": 1, "created_at": "2023-08-24T04:19:44Z", "updated_at": "2023-09-15T15:58:22Z", "ends_at": "2024-08-31T18:00:00Z" } ``` **Response object schema:** Name Type Description `customer_account_uid` string TThe unique identifier (UID) for the customer's billing account. The UID can be up to 80 characters long with any combination of alphanumeric characters and hyphens. `account_type` string The type of 1Password account you provisioned for the customer: `I` for individual account or `F` for family account. `activation_token` string The activation token you'll use to create a link that connects the customer's new or existing 1Password account to their partner billing account (for example, `https://start.[1password_domain]/partnership/redeem?t=[account_type]&c=[activation_token]&l=[language_code]`). Tokens can only be used with a 1Password individual or family account. Team and business accounts aren't supported. `domain` string The domain for the new or existing 1Password account the customer can use with the partner billing service. For the test server: `b5test.com`, `b5test.ca`, or `b5test.eu`. For the production server: `1password.com`, `1password.ca`, or `1password.eu`. `status` string The status of the customer's billing account. Possible values are one of: <section> `entitled` Provisioning has been initiated, but the customer hasn't used their partner billing link with a new or existing 1Password account. `provisioned` The customer has used their partner billing link with a new or existing 1Password account, and their third-party billing account has been provisioned. </section> `deployed_members` integer The number of provisioned users in the 1Password account. `created_at` string The date and time the customer's billing account was created. Uses the ISO 8601 standard. `updated_at` string The date and time the customer's billing account was last updated. Uses the ISO 8601 standard. This field updates when there are account status changes. `ends_at` string The date and time the customer's billing account is scheduled to be removed from the partner billing service. Uses the ISO 8601 standard. If a date and time haven't been specified, the expected value is `null`. ### Error responses <details className="slim-details"> **`403` Returned when the authorization header is missing or an invalid token is specified.** **Example error:** ```json { "code": 403, "error": "forbidden", "description": "Invalid auth token." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`404` Returned when a resource or dependency of a resource isn't found.** **Example error:** ```json { "code": 404, "error": "not_found", "description": "Failed to find the requested account." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`410` Returned when a resource has been removed.** **Example error:** ```json { "code": 410, "error": "gone", "description": "The requested account is gone." } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. <details className="slim-details"> **`500` Returned on unexpected errors.** **Example error:** ```json { "code": 500, "error": "internal_server_error", "description": "Internal server error" } ``` **Error object schema:** Parameter Type Description `code` integer The HTTP response code of the error. `error` string A machine parsable string that represents the code. `description` string A description of the error. --- ## 1Password Secure Agentic Autofill # Use 1Password to securely provide credentials to AI agents 1Password Agentic Autofill gives you a secure way to provide credentials to AI agents, so they can sign in on your behalf without directly handling your secrets. Instead of providing credentials to an AI agent using unencrypted methods like plaintext secrets or environment variables, you can tell an agent to sign in to a website using 1Password. When the agent needs to sign in, you'll be prompted to approve or deny the request. After you approve, the 1Password browser extension in the agent's headless browser autofills your login details over an end-to-end encrypted channel and signs in to the website. In the future, you'll be able to see detailed audit logs that show when, where, and why the agent accessed the item. During the Early Access, you can use Agentic Autofill with [Browserbase Director ](https://www.director.ai/), Browserbase's no-code AI agent that automates web-based tasks using natural language prompts. ## How the Browserbase integration works When you set up the Browserbase integration, 1Password validates its pairing partner is director.ai and rejects any untrusted party, then establishes an end-to-end encrypted channel between your 1Password desktop app and Browserbase. When the agent needs to sign in, it sends a request over the encrypted channel to autofill items that match the login website you specified, triggering an approval prompt from your 1Password desktop app for each autofill request. If you approve the request, the item is sent encrypted to the headless 1Password browser extension, which injects only the minimum required credential data from the approved item into the login form. _[Diagram of the 1Password secure agentic autofill flow]_ 1Password protects communication using forward-rotating key material and the Noise framework that protects your data all the way from your approving 1Password device to the remote browser's webpage, ensuring your data cannot be leaked accidentally. 1Password and Browserbase exchange new key material after every autofill to provide post-compromise security for all autofills performed prior. :::note When Browserbase and 1Password are paired, Browserbase may be able to tell when an item matching an autofill request exists, even if the request is denied. ::: ### What Browserbase can do When you turn on the integration, Browserbase can: - Request to autofill items on your behalf ### What Browserbase can't do Browserbase cannot: - Access items without your approval - See a list of your items - Modify your items ## Before you get started Before you get started with the integration, you'll need to: 1. Sign up for [Browserbase Director ](https://www.director.ai/) and [1Password](https://1password.com/pricing/password-manager). 2. Install the [1Password desktop app](https://1password.com/downloads). 3. Install the [1Password browser extension](https://1password.com/downloads/browser-extension). :::tip Make sure to turn on [Touch ID](https://support.1password.com/touch-id-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or a Linux [system authentication option](https://support.1password.com/system-authentication-linux/) in the 1Password app for the best authentication experience. ::: ### Administrators: Turn on the agentic autofill policy If you're using a 1Password Business account, your administrator must turn on the agentic autofill policy for your team before you can use it. To do this, they'll need to: 1. Sign in to their account on 1Password.com. 2. Select **Policies**, then select **Manage** under "Sharing and permissions". 3. Turn on the policy "Allow AI Agents to autofill for users". ## Step 1: Connect 1Password and Browserbase To set up the integration with Browserbase: 1. Sign in to [Browserbase Director ](https://www.director.ai/). 2. Select **_[1Password browser extension]_ Connect 1Password** beneath the input field. You'll be redirected to 1Password.com. 3. Sign in to the 1Password account you want to use with Browserbase Director, then select **Continue**. If your 1Password desktop app is locked, you'll be prompted to unlock it. 4. Select **Next** to return to Browserbase Director and complete the pairing flow. After pairing, you should see a check next to the 1Password icon beneath the input field. _[The Browserbase Director prompt with 1Password toggled on]_ To turn off the integration, select the 1Password icon _[1Password browser extension]_ beneath the input field, then toggle off **1Password Autofill**. You can also select **Disconnect** to unpair 1Password and Browserbase. :::note You can currently pair Browserbase with 1Password on one device. If you set up the integration on a second device, 1Password de-authorizes the integration on the original device. ::: ## Step 2: Create an item You can create an item with sample data for a website like [autofill.me ](https://autofill.me/) to test the integration. 1. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 2. Select **+ New Item** to create a new item. 3. Select **Login** for the item category. 4. Select the username field and enter an example username like `hello`. 5. Select the password field, then select **Create a new password** to generate a random password. 6. Select the website field and enter `https://autofill.me`. If you want to test a different Login item, make sure the website is set to the URL where you sign in to the account. 7. Select **Save** to create the item. _[An example autofill.me Login]_ ## Step 3: Prompt the agent to sign in to a website using 1Password In the [Browserbase Director ](https://www.director.ai/) input field, instruct the agent to sign in to a website using 1Password and hit enter. For example, to have the agent sign in to `autofill.me` with the test Login item you created in the previous step, enter the prompt: ``` sign in to https://autofill.me/form/login-simple using 1Password ``` You'll get a prompt from 1Password asking you to authorize or cancel the request from Browserbase. If you have multiple items for the same website, you can select the down arrow next to the suggested login to choose a different item. Authorize the prompt in the same way you unlock your 1Password account, like with Touch ID, and 1Password will fill your login in the remote browser session. If you make a second request to sign in using 1Password in the same workflow, you may need to select the **Log in with 1Password** button in Browserbase Director. _[The prompt to authorize 1Password to fill credentials through Browserbase]_ ## Troubleshooting ### If Browserbase and 1Password don't pair successfully If you have trouble pairing 1Password and Browserbase, try the following steps: #### Make sure the 1Password browser extension and your 1Password desktop app are connected For the pairing process to work successfully, your 1Password browser extension and desktop app must be connected. To check if they're connected: 1. Select _[1Password browser extension]_ in your browser's toolbar, then select your account or collection in the top left > **Settings**. 2. Select **General** and make sure the "Integrate this extension with the 1Password desktop app" setting is toggled on and the integration status is connected. If your 1Password browser extension and app aren't connected, [turn on the appropriate settings](https://support.1password.com/connect-1password-browser-app#check-your-settings). #### Make sure your app is open and unlocked Before beginning the pairing process, open the 1Password desktop app and unlock it. Then, follow the steps to [connect 1Password and Browserbase](#step-1-connect-1password-and-browserbase). ### If you see a warning that the request is taking longer than expected If you see a warning from Browserbase that the request is taking longer than expected, your 1Password app may be locked. Open the 1Password desktop app and unlock it, then try the request again. If you're still having trouble or want to share feedback, [contact 1Password support](mailto:support@1password.com). ## Learn more - [Closing the credential risk gap for AI agents using a browser](https://blog.1password.com/closing-the-credential-risk-gap-for-browser-use-ai-agents/) - [The security principles guiding 1Password’s approach to AI](https://blog.1password.com/security-principles-guiding-1passwords-approach-to-ai/) --- ## Build on 1Password with LLMs {/*Links to generated .txt and .md files use full URLs so Docusaurus does not flag them as broken — these files only exist after build.*/} # Build on 1Password with LLMs 1Password developer documentation is optimized for consumption by large language models (LLMs). Whether you're using an AI coding assistant, building an agent, or working with a chatbot, you can point it to our documentation for accurate, up-to-date context about 1Password developer tools. ## Quick start Give your LLM one of these URLs depending on what you need: | What you need | URL | Size | |---|---|---| | **Full index** of all docs with descriptions | [`/llms.txt`](https://developer.1password.com/llms.txt) | ~40 KB | | **All documentation** in a single file | [`/llms-full.txt`](https://developer.1password.com/llms-full.txt) | ~1.6 MB | | **CLI** docs only | [`/llms-cli.txt`](https://developer.1password.com/llms-cli.txt) | ~800 KB | | **SDK** docs only (Python, JS, Go) | [`/llms-sdks.txt`](https://developer.1password.com/llms-sdks.txt) | ~135 KB | | **SSH & Git** docs only | [`/llms-ssh.txt`](https://developer.1password.com/llms-ssh.txt) | ~140 KB | | **Secrets Automation** (Service Accounts, Connect, CI/CD, K8s) | [`/llms-secrets-automation.txt`](https://developer.1password.com/llms-secrets-automation.txt) | ~260 KB | | **Events API** docs only | [`/llms-events-api.txt`](https://developer.1password.com/llms-events-api.txt) | ~130 KB | | **Any single page** as Markdown | Append `.md` to the URL of any article | Varies | ## How it works ### llms.txt The [`/llms.txt`](https://developer.1password.com/llms.txt) file follows the [llms.txt standard](https://llmstxt.org/), providing a structured index of all documentation pages with titles, URLs, and descriptions. This is the best place to start for any LLM. It can scan the index to find relevant pages, then retrieve individual pages as needed. ### Per-topic files If your LLM has a large enough context window, you can provide a topic-specific file that contains all the documentation for that area. For example, if you're building an integration with 1Password CLI, point your LLM to [`/llms-cli.txt`](https://developer.1password.com/llms-cli.txt) and it will have the complete CLI documentation — commands, guides, shell plugins, and all reference material — in a single request. ### Individual pages as Markdown Every documentation page is available as clean Markdown by appending `.md` to its URL. For example: - `developer.1password.com/docs/cli/get-started` → [`developer.1password.com/docs/cli/get-started.md`](https://developer.1password.com/docs/cli/get-started.md) - `developer.1password.com/docs/sdks` → [`developer.1password.com/docs/sdks.md`](https://developer.1password.com/docs/sdks.md) This is useful for retrieval-augmented generation (RAG) workflows or when you only need context about a specific topic. You can also use the **Copy page as Markdown** button at the top of any page to copy the Markdown content directly to your clipboard and paste it into your LLM conversation. ## Using 1Password docs with AI tools ### Cursor, Windsurf, and other AI IDEs Most AI coding assistants let you attach documentation context. To use 1Password developer documentation, do one of the following: - Paste the URL of a per-topic file (e.g., `https://developer.1password.com/llms-sdks.txt`) when prompted for context, or include it in your prompt. - In [Cursor](https://cursor.com/), use the `@Docs` feature to add `https://developer.1password.com/llms.txt` as a documentation source. ### ChatGPT, Claude, and other chatbots When asking an LLM about 1Password developer tools, do one of the following: - Copy the relevant per-topic file URL and ask the LLM to read it. - Use the **Copy page as Markdown** button on any docs page to copy its content, then paste it into your conversation for precise context. ### AI agents and automation If you're building an agent that needs to interact with 1Password: 1. Use [`/llms.txt`](https://developer.1password.com/llms.txt) as the entry point for your agent to discover available documentation. 2. Fetch individual pages as Markdown by appending `.md` to any URL for RAG (retrieval-augmented generation) workflows. 3. Use the [per-topic files](#quick-start) to provide scoped context for specific tasks. ## What's included The LLM-friendly files cover all 1Password developer documentation: - **[1Password CLI](/docs/cli):** Command reference, guides for secrets management, shell plugins, and scripting. - **[1Password SDKs](/docs/sdks):** Python, JavaScript, and Go SDK guides for programmatic secrets access. - **[SSH & Git](/docs/ssh):** SSH key management, Git commit signing, and SSH agent configuration. - **[Secrets Automation](/docs/service-accounts):** Service accounts, Connect server, CI/CD integrations (GitHub Actions, CircleCI, Jenkins), and Kubernetes operator. - **[Environments](/docs/environments):** 1Password Environments for managing environment variables. - **[Events API](/docs/events-api):** Events reporting API reference and integration guides. - **[Partnership API](/docs/partnership-api/reference):** API for provisioning and managing 1Password accounts programmatically. ## About the llms.txt standard The [`llms.txt` standard](https://llmstxt.org/) is an open specification for making website content accessible to LLMs. It provides a structured, machine-readable Markdown index at a well-known URL (`/llms.txt`), making it easy for AI systems to discover and consume documentation without parsing complex HTML. --- ## 1Password Cursor Hooks [1Password Cursor Hooks ](https://github.com/1Password/cursor-hooks/tree/main) provide automated validation and verification of 1Password configurations and integrations. They help make sure that required 1Password resources are properly set up before commands are executed, preventing errors and security issues. ## Available hooks - [Validate locally mounted .env files from 1Password Environments](/docs/environments/cursor-hook-validate) --- ## 1Password integrations Use integrations to securely access secrets from 1Password in your development workflows. - **Ansible**: Interact with your 1Password Connect deployment from Ansible playbooks. Create, read, update, and delete 1Password vaults and items. Learn more - **AWS ECS Fargate**: Use 1Password Connect with AWS Fargate, so you can leverage Amazon Elastic Container Service (ECS) to run containers without the need to manage clusters. Learn more - **Build with LLMs**: Point AI coding assistants, chatbots, and agents to 1Password documentation for accurate context when building integrations. Learn more - **CI/CD integrations**: Securely access secrets in your CI/CID pipelines with CircleCI, GitHub Actions, and Jenkins. Learn more - **Cursor Hooks**: Use Cursor Hooks to validate 1Password configurations and integrations, preventing errors and security vulnerabilities. Learn more - **Kubernetes integrations**: Integrate 1Password with Kubernetes Secrets Injector, Kubernetes Operator, or Helm charts. Learn more - **Postman**: Securely load API keys and other secrets stored in 1Password into Postman without exposing any secrets in plaintext. Learn more - **Pulumi**: Use the 1Password provider for Pulumi to access and manage items in your 1Password vaults. Learn more - **Pulumi ESC**: Dynamically import Secrets from 1Password into your Environment. The provider will return a map of names to Secrets. Learn more - **Terraform**: Reference, create, or update items in your vaults with a Connect server or service account. Learn more - **VS Code**: Integrate your VS Code development workflow with 1Password. Learn more --- ## Use the 1Password provider for Pulumi You can use the [1Password provider for Pulumi ](https://www.pulumi.com/registry/packages/onepassword/) to access and manage items in your 1Password vaults. ## Requirements The provider can be configured to authenticate with a service account, a Connect server, or with your 1Password account details. **Service account:** [1Password Service Accounts](/docs/service-accounts/) allow you to restrict the provider's access to specific vaults in your 1Password account, so you can follow the principle of least privilege in your project. To use a service account with the 1Password provider for Pulumi, you'll need: - [1Password subscription](https://1password.com/pricing/password-manager) - [1Password CLI](/docs/cli/get-started) - [1Password service account](/docs/service-accounts/get-started) **Connect server:** [1Password Connect Servers](/docs/connect/) are a good authentication option when you need unlimited requests and use self-hosted infrastructure. Connect servers allow you to restrict the provider's access to specific vaults in your 1Password account, so you can follow the principle of least privilege in your project. To use a Connect server with the 1Password provider for Pulumi, you'll need: - [1Password subscription](https://1password.com/pricing/password-manager) - [1Password Connect server](/docs/connect/get-started) **Account details:** When you configure the provider with your 1Password account details, the provider can access any vault in your account, and you can use Touch ID, Windows Hello, or another system authentication option with the provider. To use your account details with the 1Password provider for Pulumi, you'll need: - [1Password subscription](https://1password.com/pricing/password-manager) - [1Password CLI](/docs/cli/get-started) - [1Password desktop app*](https://1password.com/downloads/) - [1Password app integration*](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration) * To authenticate with Touch ID, Windows Hello, or another system authentication option. ## Step 1: Install the 1Password provider for Pulumi ### With a package manager **Node.js:** To use the provider with JavaScript or TypeScript in Node.js, install using either `npm` or `yarn`: **npm:** ```shell npm install @1password/pulumi-onepassword ``` **yarn:** ```shell yarn add @1password/pulumi-onepassword ``` **Python:** To use the provider with Python, install using `pip`: ```shell pip install pulumi_onepassword ``` **Go:** To use the provider with Go, use `go get` to download the latest version: ```shell go get github.com/1Password/pulumi-onepassword/sdk/go/... ``` ### With the provider binary To install the 1Password provider binary, use the [`pulumi plugin` ](https://www.pulumi.com/docs/cli/commands/pulumi_plugin/) command: ```shell pulumi plugin install resource onepassword <version> --server github://api.github.com/1Password/pulumi-onepassword ``` ## Step 2: Configure the provider with your credentials You can provide your 1Password credentials to Pulumi in the environment or in your Pulumi configuration. Your Pulumi configuration is a good option if you want to store your credentials alongside your Pulumi stack for multi-user access. **Service account:** 1. [Create a service account](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/) or find the token for an existing service account. Make sure the service account has access to the appropriate vaults and adequate permissions in those vaults. 2. Provide the token to Pulumi using either an environment variable or your Pulumi configuration. Environment variable **Bash, Zsh, sh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token> ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token> ``` **PowerShell:** ```powershell $Env:OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token> ``` Pulumi configuration ```shell pulumi config set pulumi-onepassword:service_account_token --secret #code-result Value: <paste token here> ``` Make sure to pass `--secret` when setting sensitive data. 3. Install [1Password CLI](/docs/cli/get-started) in your PATH. If you install the CLI outside of your PATH, specify the path to your 1Password CLI binary using either an environment variable or your Pulumi configuration. Environment variable **Bash, Zsh, sh:** ```shell export OP_CLI_PATH=<path-to-your-cli-binary> ``` **fish:** ```shell set -x OP_CLI_PATH=<path-to-your-cli-binary> ``` **PowerShell:** ```powershell $Env:OP_CLI_PATH=<path-to-your-cli-binary> ``` Pulumi configuration ```shell pulumi config set pulumi-onepassword:op_cli_path --secret #code-result Value: <paste path to your binary here> ``` **Connect server:** 1. [Create a Connect server](/docs/connect/get-started) or find the host URL and token for an existing Connect server. 2. Provide the host URL and token to Pulumi using either environment variables or your Pulumi configuration. Environment variables **Bash, Zsh, sh:** **Host URL** ```shell export OP_CONNECT_HOST=<your-connect-server-host-url> ``` **Token** ```shell export OP_CONNECT_TOKEN=<your-connect-server-token> ``` **fish:** **Host URL** ```shell set -x OP_CONNECT_HOST=<your-connect-server-host-url> ``` **Token** ```shell set -x OP_CONNECT_TOKEN=<your-connect-server-token> ``` **PowerShell:** **Host URL** ```shell $Env:OP_CONNECT_HOST=<your-connect-server-host-url> ``` **Token** ```shell $Env:OP_CONNECT_TOKEN=<your-connect-server-token> ``` Pulumi configuration **Host URL** ```shell pulumi config set pulumi-onepassword:url --secret #code-result Value: <paste Connect server host URL here> ``` **Token** ```shell pulumi config set pulumi-onepassword:token --secret #code-result Value: <paste Connect server token here> ``` Make sure to pass `--secret` when setting sensitive data. **Account details:** 1. Find the [sign-in address](https://support.1password.com/1password-glossary#sign-in-address) or [unique identifier](/docs/cli/reference#unique-identifiers-ids) for your 1Password account. 2. Provide your account sign-in address or identifier to Pulumi using an environment variable or your Pulumi configuration. Environment variable **Bash, Zsh, sh:** ```shell export OP_ACCOUNT=<your-account-details> ``` **fish:** ```shell set -x OP_ACCOUNT=<your-account-details> ``` **PowerShell:** ```powershell $Env:OP_ACCOUNT=<your-account-details> ``` Pulumi configuration ```shell pulumi config set pulumi-onepassword:account --secret #code-result Value: <paste your account sign-in address or unique identifier here> ``` Make sure to pass `--secret` when setting sensitive data. 3. Install [1Password CLI](/docs/cli/get-started) in your PATH. If you install the CLI outside of your PATH, specify the path to your 1Password CLI binary using either an environment variable or your Pulumi configuration. Environment variable **Bash, Zsh, sh:** ```shell export OP_CLI_PATH=<path-to-your-cli-binary> ``` **fish:** ```shell set -x OP_CLI_PATH=<path-to-your-cli-binary> ``` **PowerShell:** ```powershell $Env:OP_CLI_PATH=<path-to-your-cli-binary> ``` Pulumi configuration ```shell pulumi config set pulumi-onepassword:op_cli_path --secret #code-result Value: <paste path to your binary here> ``` 4. To use Touch ID, Windows Hello, or another system authentication option with the provider, [turn on the 1Password CLI app integration](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). ## Step 3: Use the provider See [Pulumi's documentation ](https://www.pulumi.com/registry/packages/onepassword/) to learn how to access and manage your items using the 1Password provider. ## Reference You can use either [Pulumi configuration keys ](https://www.pulumi.com/docs/concepts/config/) or environment variables to provide your 1Password credentials to Pulumi. | Configuration key | Environment variable | Description | Authentication method | | --- | --- | --- | --- | | `pulumi-onepassword:service_account_token` | `OP_SERVICE_ACCOUNT_TOKEN` | The string value of your [1Password Service Account](/docs/service-accounts/get-started) token. | Service account | | `pulumi-onepassword:url` | `OP_CONNECT_HOST` | The URL where your [1Password Connect Server](/docs/connect/) can be found. For example: `http://localhost:8080`. | Connect server | | `pulumi-onepassword:token` | `OP_CONNECT_TOKEN` | The string value of your [Connect server token](/docs/connect/concepts#connect-server-access-token). | Connect server | `pulumi-onepassword:account` | `OP_ACCOUNT` | A 1Password account [sign-in address](https://support.1password.com/1password-glossary#sign-in-address) or [unique identifier](/docs/cli/reference#unique-identifiers-ids). | Account details | | `pulumi-onepassword:op_cli_path` | `OP_CLI_PATH` | The [path to your 1Password CLI binary](/docs/cli/config-directories). Only required if 1Password CLI binary is located outside of your PATH. | Service accountAccount details| --- ## 1Password Secrets Automation Manage your secrets with a Secrets Automation workflow that allows you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure. You can manage secrets with [1Password Service Accounts](#1password-service-accounts) or [1Password Connect servers](#1password-connect-servers). ## 1Password Service Accounts [Service accounts](/docs/service-accounts/) allow you to automate secrets management in your applications and infrastructure without the need to deploy additional services. Service accounts work well for shared environments because they provide an authentication method for 1Password CLI that isn't associated with an individual. Get started with service accounts ## 1Password Connect Servers Alternatively, secure your infrastructure secrets with one or more self-hosted [Connect servers](/docs/connect/). Connect servers allow for more control, scalability, and reduced dependency on the availability of the 1Password API. While 1Password Service Accounts are capped with strict [rate limits](/docs/service-accounts/rate-limits), Connect servers cache your data in your infrastructure. This enables unlimited re-requests after the server fetches your secrets for the first time. 1Password also maintains several SDK libraries for the [Connect API](/docs/connect/api-reference/) so you can integrate with your existing applications. Get started with Connect ## Comparison Review the following comparison table to learn about the different features and limitations of service accounts and Connect servers. | | Service accounts | Connect servers | | ------------------------------------------------------ | ---------------------------------------------- | ---------------------------------------------- | | [1Password CLI](/docs/connect/cli/) | Yes | Yes | | REST API | No | Yes | | Self-hosted | No | Yes | | Infrastructure requirements | No | Yes | | Low overhead | Yes | No | | Low latency | No | Yes | | [Kubernetes integrations](/docs/k8s/integrations/) | Yes | Yes | | [CI/CD integrations](/docs/ci-cd/) | Yes | Yes | | Rate limits | Yes | No | | Request quotas | Yes | No | | Included with 1Password subscription | Yes | Yes | --- ## Use the 1Password Terraform provider With the [1Password Terraform provider ](https://github.com/1Password/terraform-provider-onepassword), you can reference, create, or update items in your vaults using a [1Password Connect Server](/docs/secrets-automation#1password-connect-servers), a [1Password Service Account](/docs/secrets-automation#1password-service-accounts), or the 1Password desktop app. ## Requirements **Connect server:** - [Create a Connect server.](/docs/connect/get-started/) **Service account:** - [Create a service account](/docs/service-accounts/get-started#create-a-service-account) **1Password app:** - Install the latest [beta release](https://support.1password.com/betas#install-a-prerelease-version-of-the-1password-app) of the 1Password desktop app. :::tip If you don't see the option to update to the latest beta in the app, you can download it directly for [Mac](https://releases.1password.com/mac/beta/), [Windows](https://releases.1password.com/windows/beta/), or [Linux](https://releases.1password.com/linux/beta/). ::: ## Get started **Connect server:** To use the 1Password Terraform provider with a Connect server: 1. Specify the Connect server token. You can set this value with the OP_CONNECT_TOKEN environment variable or with the connect_token field in the provider configuration. 2. Specify the Connect server hostname, URL, or IP address. You can set this value with the OP_CONNECT_HOST environment variable or with the connect_url field in the provider configuration. **Service account:** To use the 1Password Terraform provider with a service account, you'll need to provide your service account token. You can set this value with the OP_SERVICE_ACCOUNT_TOKEN environment variable or with the service_account_token field in the provider configuration. **1Password app:** First, turn on the "Integrate with other apps" setting in the 1Password desktop app. If you don't see this setting, make sure you've installed the [beta version](https://support.1password.com/betas#install-a-prerelease-version-of-the-1password-app) of the app. **Mac:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 4. Under Integrate with the 1Password SDKs, select **Integrate with other apps**. 5. If you want to authenticate with Touch ID, navigate to **Settings** > **[Security](onepassword://settings/security)**, then turn on **[Unlock using Touch ID](https://support.1password.com/touch-id-mac/)**. _[The Integrate with other apps setting]_ **Windows:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 4. Under Integrate with the 1Password SDKs, select **Integrate with other apps**. 5. If you want to authenticate with Windows Hello, navigate to **Settings** > **[Security](onepassword://settings/security)**, then turn on **[Unlock using Windows Hello](https://support.1password.com/windows-hello/)**. _[The Integrate with other apps setting]_ **Linux:** 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select your account or collection at the top of the sidebar. 3. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 4. Under Integrate with the 1Password SDKs, select **Integrate with other apps**. 5. If you want to authenticate the same way you sign in to your Linux account, navigate to **Settings** > **[Security](onepassword://settings/security)**, then turn on **[Unlock using system authentication](https://support.1password.com/system-authentication-linux/)**. _[The Integrate with other apps setting]_ Then provide your account name or ID in the provider configuration: 1. Get the name of your 1Password account as it appears at the top of the left sidebar in the 1Password desktop app. Alternatively, you can use [1Password CLI](/docs/cli/get-started) to run `op account get` to find your account ID. 2. Set the OP_ACCOUNT environment variable or account in the provider configuration to your account name or ID. Run a Terraform command that requires authentication, and you'll be prompted to authenticate in the same way you unlock your 1Password app, like with biometrics or your 1Password account password. ## Reference The following sections contain reference information for the 1Password Terraform provider: - [Configuration](#configuration) - [Resources](#resources) - [Data sources](#data-sources) ### Configuration The 1Password Terraform provider has fields you must set before you can use it with a 1Password Connect server, service account, or the 1Password desktop app. The following table describes each field. | Field | Type | Description | Required | | ------------------------ | ------ | ------------------------------------------------------------ | ------------------------------------ | | connect_token | String | A valid token for the 1Password Connect server. You can also source the value from the OP_CONNECT_TOKEN environment variable. | Required if using a Connect server. | | connect_url | String | The HTTP(s) URL of the 1Password Connect server. You can also source the value from the OP_CONNECT_HOST environment variable. | Required if using a Connect server. | | service_account_token | String | A valid token for the 1Password Service Account. You can also source the value from the OP_SERVICE_ACCOUNT_TOKEN environment variable. | Required if using a service account. | | account | String | The 1Password account name as it appears at the top left of the sidebar in the 1Password desktop app. Alternatively, the 1Password account ID. You can also source the value from the ACCOUNT environment variable. | Required if using the 1Password desktop app integration. | You can use the following environment variables to specify configuration values. | Environment variable | Description | Configuration field | | -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | | OP_CONNECT_TOKEN | A valid token for the 1Password Connect server. | connect_token | | OP_CONNECT_HOST | The hostname, IP address, or URL of the 1Password Connect server. | connect_url | | OP_SERVICE_ACCOUNT_TOKEN | A valid token for the 1Password Service Account. | service_account_token | | OP_ACCOUNT | The 1Password account name as it appears at the top left of the sidebar in the 1Password desktop app. Alternatively, the 1Password account ID. | account | #### Configuration examples The following code blocks show configuration examples. :::tip The following examples use environment variables. Make sure to set the environment variables beforehand or use plain text. ::: **Connect server:** The following example shows a provider configuration using a Connect server: ```terraform [{ "color": "dahlia", "lineNo": 2, "substr": "OP_CONNECT_HOST" }, { "color": "sunbeam", "lineNo": 3, "substr": "OP_CONNECT_TOKEN" }] title="connect-example.tf" provider "onepassword" { connect_url = "OP_CONNECT_HOST" connect_token = "OP_CONNECT_TOKEN" } ``` **Service account:** The following example shows a provider configuration using a service account: ```terraform [{ "color": "tangerine", "lineNo": 2, "substr": "OP_SERVICE_ACCOUNT_TOKEN" }] title="service-account-example.tf" provider "onepassword" { service_account_token = "OP_SERVICE_ACCOUNT_TOKEN" } ``` **1Password app:** The following example shows a provider configuration using the 1Password desktop app: ```terraform [{ "color": "lagoon", "lineNo": 2, "substr": "OP_ACCOUNT" }] title="1password-account-example.tf" provider "onepassword" { account = "OP_ACCOUNT" } ``` ### Resources The 1Password Terraform provider has the following resources: - [`onepassword_item` resource](#item-resource) #### Item resource The `onepassword_item` resource represents a 1Password item. You can import a `onepassword_item` with the following syntax: ```shell url=https://github.com/1Password/terraform-provider-onepassword/blob/main/examples/resources/onepassword_item/import.sh terraform import onepassword_item.<item_name> vaults/<vault_uuid>/items/<item_uuid> ``` ##### Schema The following tables describe the `onepassword_item` resource schema. | Field | Type | Description | Required | Access | | ----------------- | ------------------ | ------------------------------------------------------------ | -------- | ---------- | | `vault` | String | The UUID of the vault the item is in. | Yes | Read-Write | | `category` | String | The category of the item. **Acceptable values**: `login`, `password`, or `database`. | No | Read-Write | | `database` | String | The name of the database. Only applies to the database category. | No | Read-Write | | `hostname` | String | The address where the database can be found. Only applies to the database category. | No | Read-Write | | `note_value` | String, Sensitive | Secure note value. | No | Read-Write | | `note_value_wo` | String, Sensitive | A write-only secure note value. This value is not stored in the state and is intended for use with ephemeral values. Requires Terraform 1.11 or later. | No | [Write-only ](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) | | `note_value_wo_version` | Number | An integer that must be incremented to trigger an update to the `note_value_wo` field. | No | [Write-only ](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) | | `password` | String, Sensitive | The password for the item. | No | Read-Write | | `password_recipe` | Block List, Max: 1 | The password recipe for the item. Only applies to Login and Password items. See [`password_recipe`](#password_recipe). | No | Read-Write | | `password_wo` | String, Sensitive | A write-only password. This value is not stored in the state and is intended for use with ephemeral values. Requires Terraform 1.11 or later. | No | [Write-only ](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) | | `password_wo_version` | Number | An integer that must be incremented to trigger an update to the `password_wo` field. | No | [Write-only ](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) | | `port` | String | The port the database is listening on. Only applies to the database category. | No | Read-Write | | `section` | Block List | A list of custom sections in the item. See [`section`](#section). | No | Read-Write | | `section_map` | Map of Object | A map of custom sections for the item, where `label` is the map key. See [`section_map`](#section_map). | No | Read-Write | | `tags` | List of String | An array of strings representing the tags assigned to the item. | No | Read-Write | | `title` | String | The title of the item. | No | Read-Write | | `type` | String | The type of database. Only applies to the database category. **Acceptable values**: `db2`, `filemaker`, `msaccess`, `mssql`, `mysql`, `oracle`, `postgresql`, `sqlite` or `other`. | No | Read-Write | | `url` | String | The primary URL for the item. | No | Read-Write | | `username` | String | The username for the item. | No | Read-Write | | `id` | String | The Terraform resource identifier for the item in the format `vaults/<vault_id>/items/<item_id>`. | N/A | Read-Only | | `uuid` | String | The UUID of the item. Item identifiers are unique within a specific vault. | N/A | Read-Only | ###### `password_recipe` :::tip Password recipes can only be added to Login and Password items. ::: The nested schema for the `password_recipe` field: | Field | Type | Description | Required | Access | | --------- | ------- | -------------------------------------------------- | -------- | ---------- | | `digits` | Boolean | Use digits `[0-9]` when generating the password. | No | Read-Write | | `length` | Number | The length of the password to be generated. | No | Read-Write | | `symbols` | Boolean | Use symbols `[!@.-_*]` when generating the password. | No | Read-Write | ###### `section` The nested schema for the `section` field: | Field | Type | Description | Required | Access | | ------- | ---------- | ------------------------------------------------------------ | -------- | ---------- | | `label` | String | The label for the section. | Yes | Read-Write | | `field` | Block List | A list of custom fields in the section. See [`section.field`](#item-resource-section-field). | No | Read-Write | | `id` | String | A unique identifier for the section. | N/A | Read-Only | ###### `section_map` The nested schema for the `section_map` field: | Field | Type | Description | Required | Access | | ------- | ---------- | ------------------------------------------------------------ | -------- | ---------- | | `field_map` | Map of Object | A map of custom fields in the section, where `label` is the map key. See [`field_map`](#field_map). | No | Read-Write | | `id` | String | A unique identifier for the section. | N/A | Read-Only | ###### `section.field` {#item-resource-section-field} The nested schema for the `section.field` field: | Field | Type | Description | Required | Access | | ----------------- | ----------------- | ------------------------------------------------------------ | -------- | ---------- | | `label` | String | The label for the field. | Yes | Read-Write | | `id` | String | A unique identifier for the field. | No | Read-Write | | `password_recipe` | String | The password for the item. Only applies to Login and Password items. See [`section.field.password_recipe`](#item-resource-section-field-password-recipe). | No | Read-Write | | `type` | String | The type of value stored in the field. **Acceptable values**: `STRING`, `EMAIL`, `CONCEALED`, `URL`, `OTP`, `DATE`, `MONTH_YEAR`, or `MENU`. | No | Read-Write | | `value` | String, Sensitive | The value of the field. | No | Read-Write | ###### `field_map` The nested schema for the `field_map` field: | Field | Type | Description | Required | Access | | ------- | ---------- | ------------------------------------------------------------ | -------- | ---------- | | `id` | String | A unique identifier for the field. | N/A | Read-Only | | `password_recipe` | The password recipe for the field. | No | Read-Write | | `type` | String | The type of value stored in the field. | No | Read-Write | | `value` | String, Sensitive | The value of the field. | No | Read-Write | ###### `section.field.password_recipe` {#item-resource-section-field-password-recipe} :::tip Password recipes can only be added to Login and Password items. ::: The nested schema for the `section.field.password_recipe` field: | Field | Type | Description | Required | Access | | --------- | ------- | -------------------------------------------------- | -------- | ---------- | | `digits` | Boolean | Use digits `[0-9]` when generating the password. | No | Read-Write | | `length` | Number | The length of the password to be generated. | No | Read-Write | | `symbols` | Boolean | Use symbols `[!@.-_*]` when generating the password. | No | Read-Write | ##### Example The following code block shows an example usage of the `onepassword_item` resource. ```terraform url=https://github.com/1Password/terraform-provider-onepassword/blob/main/examples/resources/onepassword_item/resource.tf title="resource.tf" resource "onepassword_item" "demo_password" { vault = var.demo_vault title = "Demo Password Recipe" category = "password" password_recipe { length = 40 symbols = false } } resource "onepassword_item" "demo_login" { vault = var.demo_vault title = "Demo Terraform Login" category = "login" username = "test@example.com" } resource "onepassword_item" "demo_db" { vault = var.demo_vault category = "database" type = "mysql" title = "Demo TF Database" username = "root" database = "Example MySQL Instance" hostname = "localhost" port = 3306 } ``` ### Data sources The 1Password Terraform provider has the following data sources: - [`onepassword_item` data source](#item-data-source) - [`onepassword_vault` data source](#vault-data-source) #### Item data source Use the `onepassword_item` data source to get details of a 1Password item. You can identify an item by its vault UUID and either the item's title or UUID. ##### Schema The following tables describe the `onepassword_item` resource schema. | Field | Type | Description | Required | Access | | ------------ | ----------------- | ------------------------------------------------------------ | -------- | ---------- | | `vault` | String | The UUID of the vault the item is in. | Yes | Read-Write | | `note_value` | String, Sensitive | The Secure Note value. | No | Read-Write | | `title` | String | The title of the item to retrieve. This field populates with the title of the item if the item is looked up by its UUID. | No | Read-Write | | `uuid` | String | The UUID of the item to retrieve. This field populates with the UUID of the item if the item is looked up by its title. | No | Read-Write | | `category` | String | The category of the item. **Acceptable values**: `login`, `password`, or `database`. | No | Read-Only | | `database` | String | The name of the database. Only applies to the database category. | No | Read-Only | | `hostname` | String | The address where the database can be found. Only applies to the database category. | No | Read-Only | | `id` | String | The Terraform resource identifier for the item in the format `vaults/<vault_id>/items/<item_id>`. | No | Read-Only | | `password` | String, Sensitive | The password for the item. | No | Read-Only | | `port` | String | The port the database is listening on. Only applies to the database category. | No | Read-Only | | `section` | List of Object | A list of custom sections in an item. | No | Read-Only | | `tags` | List of String | An array of strings of the tags assigned to the item. | No | Read-Only | | `type` | String | The type of database. Only applies to the database category. **Acceptable values**: `db2`, `filemaker`, `msaccess`, `mssql`, `mysql`, `oracle`, `postgresql`, `sqlite`, or `other`. | No | Read-Only | | `url` | String | The primary URL for the item. | No | Read-Only | | `username` | String | The username for the item. | No | Read-Only | ###### `section` {#item-data-source-section} The nested schema for the `section` field: | Field | Type | Description | Required | Access | | ------- | -------------- | ------------------------------------------------------------ | -------- | ---------- | | `field` | List of Object | A list of custom fields in the section. See [`section.field`](#item-data-source-section-field). | N/A | Read-Only | | `id` | String | A unique identifier for the section. | N/A | Read-Only | | `label` | String | The label for the section. | N/A | Read-Only | ###### `section.field` {#item-data-source-section-field} The nested schema for the `section.field` field: | Field | Type | Description | Required | Access | | --------- | ----------------- | ------------------------------------------------------------ | -------- | ---------- | | `id` | String | A unique identifier for the field. | N/A | Read-Only | | `label` | String | The label for the field. | N/A | Read-Only | | `type` | String | The type of value stored in the field. **Acceptable values**: `STRING`, `EMAIL`, `CONCEALED`, `URL`, `OTP`, `DATE`, `MONTH_YEAR`, or `MENU`. | N/A | Read-Only | | `value` | String, Sensitive | The value of the field. | N/A | Read-Only | ##### Example The following example shows how to use the `onepassword_item` data source. ```terraform url=https://github.com/1Password/terraform-provider-onepassword/blob/main/examples/data-sources/onepassword_item/data-source.tf title="data-source.tf" data "onepassword_item" "example" { vault = var.demo_vault uuid = onepassword_item.demo_sections.uuid } ``` #### Vault data source Use the `onepassword_vault` data source to get details of a vault. You can identify a vault with the vault name or UUID. ##### Schema The following tables describe the `onepassword_item` resource schema. | Field | Type | Description | Required | Access | | ------------- | ------ | ------------------------------------------------------------ | -------- | ---------- | | `name` | String | The name of the vault to retrieve. This field populates with the name of the vault if the vault is looked up by its UUID. | No | Read-Write | | `uuid` | String | The UUID of the vault to retrieve. This field populates with the UUID of the vault if the vault is looked up by its name. | No | Read-Write | | `description` | String | The description of the vault. | No | Read-Only | | `id` | String | The Terraform resource identifier for this item in the format `vaults/<vault_id>`. | No | Read-Only | ### Ephemeral resources The 1Password Terraform provider has the following ephemeral resources: - [`onepassword_item` ephemeral resource](#item-ephemeral-resource) #### Item ephemeral resource The `onepassword_item` ephemeral resource represents a 1Password item. Use it to retrieve item values without storing them in Terraform state. This is useful for providing sensitive values to write-only arguments or other ephemeral contexts. ##### Schema | Field | Type | Description | Required | Access | | ------------- | ------ | ------------------------------------------------------------ | -------- | ---------- | | `vault` | String | The UUID of the vault the item is in. | Yes | Read-Write | | `title` | String | The title of the item to retrieve. This field will be populated with the title of the item if the item it looked up by its UUID. | No | Read-Write | | `uuid` | String | The UUID of the item to retrieve. This field will be populated with the UUID of the item if the item it looked up by its title. | No | Read-Write | | `credential` | String, Sensitive | API credential for this item. Only applies to the API credential category. | No | Read-Only | | `database` | String | The name of the database. Only applies to the database category. | No | Read-Only | | `hostname` | String | The address where the database can be found. Only applies to the database category. | No | Read-Only | | `id` | String | The Terraform resource identifier for the item in the format `vaults/<vault_id>/items/<item_id>`. | No | Read-Only | | `note_value` | String, Sensitive | Secure Note value. | No | Read-Only | | `password` | String, Sensitive | Password for this item. | No | Read-Only | | `port` | String | The port the database is listening on. Only applies to the database category. | No | Read-Only | | `private_key` | String, Sensitive | SSH Private Key in PKCS#8 for this item. | No | Read-Only | | `private_key_openssh` | String, Sensitive | SSH Private key in OpenSSH format. | No | Read-Only | | `public_key` | String | SSH Public Key for this item. | No | Read-Only | | `type` | String | The type of database or API Credential. Only applies to database and API credential categories | No | Read-Only | | `url` | String | The primary URL for the item. | No | Read-Only | | `username` | String | Username for this item. | No | Read-Only | #### Example ```terraform # Example using ephemeral resource to retrieve item values ephemeral "onepassword_item" "example" { vault = "your-vault-id" title = "your-item-title" } # Example using UUID instead of title ephemeral "onepassword_item" "example_by_uuid" { vault = "your-vault-id" uuid = "your-item-uuid" } ``` ## Learn more - [Changelog](https://github.com/1Password/terraform-provider-onepassword/blob/main/CHANGELOG.md) --- ## 1Password for VS Code 1Password for VS Code provides you with a set of tools to integrate your development workflow with 1Password, powered by [1Password CLI](/docs/cli/). ## Requirements Before you can use the VS Code extension, you'll need to: - Install 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). - Install the latest version of [1Password CLI](/docs/cli/get-started#step-1-install-1password-cli). - [Integrate 1Password CLI with the 1Password app.](/docs/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration) ## Installation You can install the 1Password for VS Code extension through the VS Code Marketplace or GitHub. **VS Code Marketplace:** The best way to install the 1Password for VS Code extension is through the VS Code Marketplace because it keeps the extension up to date automatically. Install from the Marketplace **GitHub:** You can also install 1Password for VS Code directly from GitHub. This option works well if you don't want automatic updates, or you want to use an older version of the extension. The GitHub Releases page lists all previous releases. Releases include a [VSIX file ](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-from-a-vsix) that you can install in VS Code. Install from GitHub After installation, the extension prompts you to choose a 1Password account and vault. :::warning[caution] You must select a 1Password account and vault to use the extension's features. ::: You can select an account and vault later through the [Command Palette ](https://code.visualstudio.com/api/ux-guidelines/command-palette): 1. Open the **Command Palette**. 2. Enter `1Password: Choose account` to select a 1Password account. 3. Enter `1Password: Choose vault` to select a vault. ## Extension settings 1Password for VS Code has a few settings you can configure. To access the 1Password for VS Code settings: 1. Go to **Code** > **Preferences** > **Settings**. 2. Scroll to or search for **1Password**. The following table lists the extension settings. | Name | Setting ID | Default Value | Details | | -------------------------------- | ------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Items: Cache Values** | `1password.items.cacheValues` | `true` | Use CLI cache when performing operations. Learn more about [caching](/docs/cli/reference#cache-item-and-vault-information). | | **Items: Password Recipe** | `1password.items.passwordRecipe` | `"letters,digits,symbols,32"` | The recipe to use when generating passwords. Learn more about [password recipes](/docs/cli/reference/management-commands/item#generate-a-password). | | **Items: Use Secret References** | `1password.items.useSecretReferences` | `true` | Use secret reference syntax for storing and retrieving values. Learn more about [secret references](/docs/cli/secret-reference-syntax/). | | **Editor: Suggest Storage** | `1password.editor.suggestStorage` | `true` | Suggest storing a value when it looks like a secret. | | **Debug: Enabled** | `1password.debug.enabled` | `false` | Log debugger data. Reload required. | ## Feature The best defense against secrets leaking from your code is for them not to be in your code to start with. To help with this, we've introduced secret references, and 1Password for VS Code is built with them in mind. [Learn more](/docs/cli/secret-reference-syntax/) and read further down to see how we're making it easy to use secret references in VS Code. By default, all operations use secret references when retrieving and storing item fields. If you'd rather not use secret references, you can turn off the "Items: Use Secret References" setting to instead insert or keep the raw field values. You can use the 1Password VS Code plugin to: - [Save in 1Password](#save-in-1password) - [Detect secrets](#detect-secrets) - [Get values from 1Password](#get-values) - [Create secrets](#create-secrets) - [Preview secret references](#preview-secret-references) - [Open secrets in 1Password](#open-secrets-in-1password) ### Save in 1Password You can use the 1Password extension to save items in 1Password from code in your document: 1. Select an exposed secret in a file. 2. Open the **[Command Palette ](https://code.visualstudio.com/api/ux-guidelines/command-palette)**. 3. Enter `1Password: Save in 1Password`. 4. Provide a name for the item. The extension prompts you to fill out the item name and a field from each selection. It automatically tries to infer the field label if it looks like an email, URL, or credit card. After creating the item (and saving it in 1Password), the extension replaces the selection with a secret reference pointing to that item and field. :::tip You can save multiple items at the same time by selecting more than one item in the file before opening the [Command Palette ](https://code.visualstudio.com/api/ux-guidelines/command-palette). [Learn more about multiple selections in VS Code ](https://code.visualstudio.com/docs/editor/codebasics#_multiple-selections-multicursor). ::: ### Detect secrets 1Password for VS Code automatically watches for bits of code that look like secrets and offers to store them in 1Password. The behavior varies slightly between regular files and `.env` files: - It checks for strings that match known secret patterns across all regular files. - It inspects `.env` files for keywords to make an educated guess if the value is a secret. When the extension finds a match, it displays a "Save in 1Password" [CodeLens ](https://learn.microsoft.com/en-us/visualstudio/ide/find-code-changes-and-other-history-with-codelens) above the line that you can select to save the secret in 1Password. You can control this feature with the "Editor: Suggest Storage" [setting](#extension-settings). ### Get values from 1Password {#get-values} The 1Password for VS Code extension allows you to use values that already exist in 1Password in your code: 1. Open the **[Command Palette ](https://code.visualstudio.com/api/ux-guidelines/command-palette)**. 2. Enter `1Password: Get from 1Password`. 3. Enter the item name or UUID. 4. Select the field to use. The extension inserts a secret reference pointing to that item and field. :::tip Already know the vault, item, and field you want to use? Start typing `secret reference` or `op://`. The extension provides a code snippet for you to fill out the individual parts of a secret reference. ::: ### Create secrets You can create secrets for your project from VS Code: 1. Place your cursor in the document. 2. Open the **[Command Palette ](https://code.visualstudio.com/api/ux-guidelines/command-palette)**. 3. Type `1Password: Generate password` in the Command Palette. 4. Enter a name for your item. The 1Password VS Code extension creates the item with a randomly generated password and inserts a secret reference in the document pointing to that item and field. :::tip You can use the "Editor: Password Recipe" [setting](#extension-settings) to customize the recipe 1Password for VS Code uses to generate passwords. ::: ### Preview secret references 1Password for VS Code analyzes open documents and looks for secret references, underlining each one it finds. It also allows you to preview individual secret references or load the secret reference values in a file. To inspect the details of a secret reference: 1. Hover your cursor over the secret reference. The secret reference details appear in a VS Code [CodeLens ](https://learn.microsoft.com/en-us/visualstudio/ide/find-code-changes-and-other-history-with-codelens). The [CodeLens ](https://learn.microsoft.com/en-us/visualstudio/ide/find-code-changes-and-other-history-with-codelens) window only displays non-sensitive information about the secret, like the creation date. It doesn't show values of sensitive fields (such as passwords and SSH keys). To preview what a file looks like with its secret references converted to real values: 1. Select the unlock icon () found in the top-right of a document. This opens an unsaved copy of your document with the secret references replaced with real values, which you can then save or delete. :::tip On Mac and Linux, you can also show a file's secrets through the Command Palette using the "1Password: Preview with secrets" command. ::: ### Open secrets in 1Password You can open a secret reference in the 1Password application by holding <kbd>Option</kbd>, then selecting the secret reference. Alternatively, you can hover your cursor over the secret reference, then select **Follow link** in the [CodeLens ](https://learn.microsoft.com/en-us/visualstudio/ide/find-code-changes-and-other-history-with-codelens) window. ## Contributing and feedback 1Password for VS Code is an open source project. If you discover a problem or want to share feedback, [open a GitHub issue. ](https://github.com/1Password/op-vscode/issues/new) Everyone is welcome to contribute to the extension. Refer to the [contribution guidelines ](https://github.com/1Password/op-vscode/blob/main/CONTRIBUTING.md) for more information. --- ## 1Password Developer Watchtower 1Password Developer Watchtower can check for developer credentials stored on your local disk and alert you about credentials that don't follow best security practices, such as credentials stored in plaintext or SSH keys that use outdated cryptography. To help you remediate any issues and mitigate security risks, Developer Watchtower provides recommendations relevant to each alert, like if you should encrypt a local SSH key or import it into 1Password. ## Requirements Before you can use Developer Watchtower, you'll need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). This feature is not available in 1Password for iOS or Android. ## Set up 1Password Developer Watchtower ### Step 1: Turn on 1Password Developer 1. Open and unlock the 1Password desktop app. 2. Select your account or collection at the top of the sidebar and choose **Settings** > [**Developer**](onepassword://settings/developers). 3. Turn on **Show 1Password Developer experience**. Learn more about [1Password Developer](https://support.1password.com/developer/). ### Step 2: Check for developer credentials on disk 1. Select **Developer** in the sidebar of the 1Password desktop app. 2. Select **View Developer Watchtower**. 2. Turn on **Check for developer credentials on disk**. Then [view your results](#step-3-view-your-results-in-developer-watchtower) in Developer Watchtower. 1Password only uses your local disk to check for developer credentials, and no one at 1Password can see or access your data. Learn more about data retention and privacy with [1Password Developer](https://support.1password.com/developer#data-retention-and-privacy) and [Watchtower](https://support.1password.com/watchtower-privacy/). ### Step 3: View your results in Developer Watchtower 1Password will list any credentials it finds on disk under one of the following categories, according to the attributes with the highest security impact: - **Needs attention**: Credentials that are known to be vulnerable and pose some level of security risk. - **Recommendations**: Credentials that could benefit from additional key management. Select an item in the list to reveal information about the credential along with recommendations and suggested actions. Select the item's action menu to see options to show the credential in your file manager, copy relevant metadata, delete the SSH key from disk, and more. :::info SSH keys are the only developer credentials currently supported in Developer Watchtower, so your results won't include other credentials you may have stored on your local disk. ::: ## SSH keys found on disk 1Password checks your local disk for SSH keys in the following location and formats: | Location | Credential type | | --------- | --------- | | `~/.ssh` (up to 3 nested directories) | SSH private keys in OpenSSH, PKCS#8, or PKCS#1 format | 1Password doesn't follow symlinks or traverse file systems (for example, an external drive mounted at `~/.ssh/other` will be skipped). Files over 1 MiB (mebibyte) in size are also skipped. If any SSH keys are found within these parameters, they'll be added to Developer Watchtower to alert you to security issues and provide recommendations to improve your SSH key management. ### SSH key alerts | Alert message | Description | Recommended Action | | ----- | --------- | --------- | | Insecure key type | An SSH key in an outdated format that's known to be vulnerable. | Remove the public key from the `authorized_keys` file of any server and service you've used it with. Then generate a new, secure SSH key in 1Password and delete the insecure key file from disk. [Learn more.](#insecure-key-type) | | This key is unencrypted | An SSH key stored in plaintext on disk. | Import the key into 1Password and remove the unencrypted copy from your disk, or use the `ssh-keygen` command to encrypt the file on disk. [Learn more.](#unencrypted-key)| | Already exists in 1Password | An SSH key you've already saved in 1Password. | Delete the redundant copy of your SSH key on disk and keep the key you've already secured in 1Password. [Learn more.](#already-exists-in-1password) | | Unsupported key | An SSH key that isn't supported in 1Password. | Generate a new SSH key in 1Password if you want to use it with the 1Password SSH Agent. [Learn more.](#unsupported-keys) | #### Insecure key type {#insecure-key-type} An insecure SSH key is a critical security issue that needs to be addressed. Insecure keys are vulnerable to being cracked, which can provide attackers with the ability to infiltrate and compromise servers. Insecure keys include: - DSA keys - RSA keys less than 2048 bits in strength [OpenSSH ](https://lists.mindrot.org/pipermail/openssh-unix-announce/2024-January/000156.html) is removing support for these insecure key types, along with major developer platforms like [GitHub ](https://github.blog/2021-09-01-improving-git-protocol-security-github/) and GitLab. If Developer Watchtower alerts you to an insecure SSH key, it's imperative that you remove the SSH key file from your disk *and* from the `authorized_keys` file of every server it's used with. First, remove the insecure key from the `authorized_keys` file of every server, or from any service, where it's used. Next, [generate a new, secure SSH key in 1Password](/docs/ssh/manage-keys#generate-an-ssh-key) and use the new key to replace the insecure key anywhere it was used. Then, in Developer Watchtower, select the action menu for the insecure key and choose **Delete SSH key from disk** to permanently remove the key from disk. #### Unencrypted key {#unencrypted-key} A private key file stored in plaintext is a security vulnerability and provides [an easy target for malware. ](https://www.scmagazine.com/news/github-npm-registry-abused-to-host-ssh-key-stealing-malware) Encrypting your SSH private keys with passphrases provides another layer of protection and is a common practice supported by SSH clients. If Developer Watchtower alerts you to an unencrypted key on your local disk, you can choose one of the following options from the action menu: - **Import**: When you import an SSH key into 1Password, it's [automatically encrypted for you](https://support.1password.com/1password-security#encryption). After you import the key into 1Password, you can permanently remove the redundant copy from your disk. Select the action menu for the unencrypted key in Developer Watchtower and choose **Delete SSH key from disk**. - **Copy Encryption Command**: If you prefer to keep a copy on disk, you should encrypt the key file with a passphrase. This option copies the `ssh-keygen` command to your clipboard, including the path to your key. You can run the command in your terminal app: ```shell ssh-keygen -pf path/to/your/key ``` The `-pf` flag prompts you to create a passphrase and specify the private key file you want to encrypt. #### Already exists in 1Password {#already-exists-in-1password} 1Password compares the public fingerprint of the SSH key on your local disk with the fingerprints of your SSH Key items in 1Password to determine if you've already saved the key there. If Developer Watchtower indicates that a key in your local `~/.ssh` folder has already been saved 1Password, you can remove the redundant copy of the SSH key on disk. Select the item's action menu and choose **Delete SSH key from disk** to permanently remove the key from disk. #### Unsupported keys An SSH key that isn't [supported in 1Password](/docs/ssh/manage-keys#supported-ssh-key-types) can't be imported. 1Password supports the following key types and formats: - Ed25519 keys - RSA 2048, 3072, and 4096-bit keys If Developer Watchtower lets you know that a key on your local disk is unsupported, consider [generating a new SSH key](/docs/ssh/manage-keys#generate-an-ssh-key) if you want to use it with the [1Password SSH Agent](/docs/ssh/agent). You may also be able to convert some keys to a format 1Password does support. For example, 1Password doesn't support keys in the PuTTY format (`.ppk`), but [PuTTYgen ](https://www.puttygen.com/) lets you export your PPK keys into the OpenSSH format. ## Ignore files If you want 1Password to ignore specific files in your `~/.ssh` folder when checking for developer credentials, you can create a `.ignore` file in your SSH folder. Add entries to the `~/.ssh/.ignore` file to specify any files 1Password should ignore. For example: ```text title="Example entries in ~/.ssh/.ignore file" test_key *_development ``` --- ## Add the Save in 1Password button to your website When you add the Save in 1Password button to your website, visitors can easily save their sign-in details, credit cards, or crypto wallets to their 1Password account in one step. If you set up an integration with 1Password, the button can also be used to save API keys. The Save in 1Password button on your site communicates directly with 1Password in the browser, so no unencrypted information leaves the customer's browser. _[]_ ## Add the button to your site To add the button to your site, you'll need to install the Save in 1Password button, build a save request, and import the button into your file with the required attributes and values. The button is disabled by default. When the page loads, 1Password will check for the button and make it available to the user. Item URLs, if applicable, are determined by 1Password, so a login item can only be filled for the domain on which it was saved. The button element specifies the type of item to create and the information it'll contain. The information is a Base64-encoded save request in JSON format. ### Install the button To get started, install the [Save in 1Password button](https://www.npmjs.com/package/@1password/save-button) using your preferred package manager: **npm:** ```shell npm install @1password/save-button --save-dev ``` **Yarn:** ```shell yarn add @1password/save-button -D ``` Then import the package into your HTML file. For example: ```html <script type="module"> </script> ``` ### Build a save request The save request needs these values: | Field | Type | Description | |-------|------|------------| | `title` | string | The suggested title for the item to be saved. | | `fields` | array | Each object in the array has these properties: `autocomplete` (string): The type of field to fill.`value` (string): The value to be filled in the field Use the autocomplete field name and values defined in the Autofill section of the [HTML Living Standard](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill). The custom autocomplete fields for Crypto Wallet items are `crypto-address` for wallet address and `crypto-recovery-seed` for recovery phrase. The custom autocomplete fields for Login items are `one-time-code` for one-time password fields and `recovery-code` for an individual masked recovery code. | | `notes` (optional) | string | Notes to save with the item. These can be formatted with Markdown. | For example: ```javascript const saveRequest = { title: "ACME Credit Card", fields: [ { autocomplete: "cc-name", value: "Wendy J. Appleseed", }, { autocomplete: "cc-number", value: "4111111111111111", }, { autocomplete: "cc-exp", value: "202512", }, { autocomplete: "cc-csc", value: "123", }, { autocomplete: "cc-type", value: "visa", }, { autocomplete: "street-address", value: "512 Main Street", }, { autocomplete: "address-level2", value: "Cambridge", }, { autocomplete: "address-level1", value: "MA", }, { autocomplete: "postal-code", value: "12345", }, { autocomplete: "country", value: "US", }, ], notes: "Plain text. You can use [Markdown](https://support.1password.com/markdown/) too.", }; ``` To encode the example above to a Base64 string in JSON format, use the built-in `encodeOPSaveRequest` function: ```javascript const encodedSaveRequest = encodeOPSaveRequest(saveRequest); ``` Then copy and paste the resulting Base64-encoded string as the `value` attribute of the Save in 1Password button. For example: ``` "eyJ0aXRsZSI6IkFDTUUgQ3JlZGl0IENhcmQiLCJmaWVsZHMiOlt7ImF1dG9jb21wbGV0ZSI6ImNjLW5hbWUiL CJ2YWx1ZSI6IldlbmR5IEouIEFwcGxlc2VlZCJ9LHsiYXV0b2NvbXBsZXRlIjoiY2MtbnVtYmVyIiwidmFsdW UiOiI0MTExMTExMTExMTExMTExIn0seyJhdXRvY29tcGxldGUiOiJjYy1leHAiLCJ2YWx1ZSI6IjIwMjUxMiJ 9LHsiYXV0b2NvbXBsZXRlIjoiY2MtY3NjIiwidmFsdWUiOiIxMjMifSx7ImF1dG9jb21wbGV0ZSI6ImNjLXR5 cGUiLCJ2YWx1ZSI6InZpc2EifSx7ImF1dG9jb21wbGV0ZSI6InN0cmVldC1hZGRyZXNzIiwidmFsdWUiOiI1M TIgTWFpbiBTdHJlZXQifSx7ImF1dG9jb21wbGV0ZSI6ImFkZHJlc3MtbGV2ZWwyIiwidmFsdWUiOiJDYW1icm lkZ2UifSx7ImF1dG9jb21wbGV0ZSI6ImFkZHJlc3MtbGV2ZWwxIiwidmFsdWUiOiJNQSJ9LHsiYXV0b2NvbXB sZXRlIjoicG9zdGFsLWNvZGUiLCJ2YWx1ZSI6IjEyMzQ1In0seyJhdXRvY29tcGxldGUiOiJjb3VudHJ5Iiwi dmFsdWUiOiJVUyJ9XSwibm90ZXMiOiJQbGFpbiB0ZXh0LiBZb3UgY2FuIHVzZSBbTWFya2Rvd25dKGh0dHBzO i8vc3VwcG9ydC4xcGFzc3dvcmQuY29tL21hcmtkb3duLykgdG9vLiJ9" ``` Or update the Base64-encoded value of the button: ```javascript document .querySelector("onepassword-save-button") .shadowRoot.querySelector("button[data-onepassword-save-button]") .setAttribute("value", encodedSaveRequest); ``` ### Add the button to your page Add the Save in 1Password button to your page with the two required attributes: `data-onepassword-type` and `value`. You can also add optional attributes to change the button language, color, theme, or padding: `lang`, `class`, `data-theme`, or `padding`. | Attribute | Value | |----------|------| | `data-onepassword-type` | The type of item the button will create: `credit-card`, `login`, or `crypto-wallet`. | | `value` | The Base64-encoded [save request](#build-a-save-request). | | `lang` (optional) | The language code for [one of the supported languages](#appendix-supported-language-codes). If no language attribute is provided, the package will determine the browser language using the [NavigatorLanguage Web API](https://www.science.co.il/language/Locale-codes.php). If the browser language isn't supported, the package will default to English. | | `class` (optional) | The color of the button: `black` or `white`. If no class attribute is provided, the button color will default to blue. | | `data-theme` (optional) | The optimized button theme for a website with a light or dark background: `light` or `dark`.If no data-theme attribute is provided, the button will default to the light theme. | | `padding` (optional) | The button padding: `normal` or `compact` or `none`. If no value is provided, or if the value is `normal`, the button padding will default to 24 pixels. If the value is `compact`, the padding will be 16 pixels. If the value is `none`, the padding will be 0 pixels. | For example: ```html <onepassword-save-button data-onepassword-type="credit-card" value="eyJ0aXRsZSI6IkFDTUUgQ3JlZGl0IENhcm...==" lang="en" class="black" data-theme="dark" padding="normal"> </onepassword-save-button> ``` If you're building a single-page app, you may need to call the `activateOPButton()` function to activate the button. This will dispatch a custom event on the page to tell 1Password to enable the Save in 1Password button. ## Appendix: Supported language codes | Language | Code | Language | Code | Language | Code | |----------|------|------------|------|------------|------| | English | `en` | Japanese | `ja` | Spanish | `es` | | French | `fr` | Korean | `ko` | Chinese, simplified | `zh-CN` | | German | `de` | Portuguese | `pt` | Chinese, traditional | `zh-TW` | | Italian | `it` | Russian | `ru` | | | --- ## Design your website to work best with 1Password 1Password is designed to generate, fill, and save passwords on most websites. You shouldn't have to do anything special to support 1Password on your website, as long as you develop your pages according to best practices. This will make the intention of each page element clear. 1Password will have an easier time understanding your page even when you make changes to it. :::tip 1Password also supports [saving and signing in with passkeys](https://support.1password.com/save-use-passkeys/). Learn how to [design your website to work with passkeys](https://passkeys.dev/docs/intro/what-are-passkeys/). ::: ## Build logical forms If 1Password has trouble saving or filling on your site, make sure you're following best practices with your forms: - Use a unique element `id` or `name` for every field and form. - Enclose `<input>` fields in `<form>` elements. - Group related fields (like usernames and passwords) together in the same `<form>` element. - Separate unrelated fields into different `<form>` elements. For example, put registration and sign-in fields in different forms. - Set the correct `method` on the form. The 1Password browser extension will automate a button click with `element.click()`. If your form doesn't specifically handle this case, the form may be submitted with `get`, which bypasses other listeners and could unintentionally leak credentials in the URL. ### Ignore offers to save or fill specific fields If you don't want 1Password to offer to save or fill on a field, you can use the `data-1p-ignore` or `data-op-ignore` attribute to tell 1Password it should ignore the field. For example: ```html <input type="text" id="username" name="ig" data-1p-ignore> ``` If your tools don't accept data attributes that start with a digit, you can use `data-op-ignore` instead. ### Password change and reset forms On password change forms, ask for the current password, the new password, and a password confirmation in that order. This makes the intention of each form element clear. For example: ```html <label for="current-password">Current Password: </label> <input type="password" name="current-password" id="current-password" autocomplete="current-password" /> <label for="password">New Password: </label> <input type="password" name="new-password" id="new-password" autocomplete="new-password" /> <label for="confirm-password">Confirm Password: </label> <input type="password" name="confirm-password" id="confirm-password" autocomplete="new-password" /> ``` On password reset and "forgot password" forms, include the username for the password that is being reset. This helps 1Password determine which item to update with the new password. For example: ```html <input style="display: none;" type="text" name="username" id="username" autocomplete="username" value="wendy.appleseed" /> <label for="password">New Password: </label> <input type="password" name="password" id="new-password" autocomplete="new-password" /> ``` ## Provide password requirements 1Password can generate passwords that fit your website's password requirements. 1Password uses Apple's [Password Manager Resources ](https://github.com/apple/password-manager-resources) to identify a website's unique password rules along with the [shared credential backends ](https://github.com/apple/password-manager-resources/blob/main/quirks/websites-with-shared-credential-backends.json) file in the same repository for multiple domains that share the same account system. To provide the rules 1Password will use to generate smart passwords, add the following attributes to each `<input type="password">` element: - `passwordrules` - `minlength` - `maxlength` [Learn how to create a `passwordrules` attribute. ](https://developer.apple.com/password-rules/) ## Embrace accessibility Making your website accessible benefits everyone who uses your website. As a bonus, making your site accessible provides clues to 1Password as well. When examining a page, 1Password can take advantage of accessibility cues to locate fields: - Give every field a `<label>` element. - Use the `for` attribute on your labels to associate them with the appropriate field: ```html <label for="username-field">Username</label> <input name="username" id="username-field"> ``` - Use [ARIA attributes ](https://developer.mozilla.org/docs/Web/Accessibility/ARIA) to annotate form fields. For example, use the `aria-hidden` attribute on fields that aren't visible. ## Improve reliability Follow these additional guidelines to make sure 1Password will always work with your site, even when you make changes to it: - Use `placeholder` attributes on fields instead of overlays. - Don't use generated field names and IDs. - Don't dynamically add or remove fields from the DOM. Reuse fields and hide them when you don't need them. - Use the appropriate `autocomplete` attributes on fields. These attributes make it easier for 1Password to identify your fields. Refer to [this list of available attributes ](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill). For example, add `autocomplete="one-time-code"` to a field where someone can enter a one-time password. ## Get help Make sure you're testing with [the latest 1Password beta release](https://support.1password.com/betas/). If you're still having trouble after following the guidelines above, [get help from the 1Password Support Community](https://1password.community/categories/saving-and-filling-logins).