Get started with a 1Password Connect server

1Password Connect servers are a type of Secrets Automation workflow 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.
• Create a vault for the Connect server to access. Connect servers can't access your built-in Personal, Private, or Employee vault, or your default Shared vault.
• Make sure you belong to a group with permission to manage Secrets Automation.
• 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.
• Create a vault for the Connect server to access. Connect servers can't access your built-in Personal, Private, or Employee vault, or your default Shared vault.
• Make sure you belong to a group with permission to manage Secrets Automation.
• Make sure you have a deployment environment for Kubernetes with kubectl , and Helm 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

You can create a Connect server Secrets Automation workflow through the 1Password.com dashboard or the 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. You can issue additional tokens later.

1Password.com

1. Sign in to your account on 1Password.com.
2. Select Developer Tools from the sidebar.
3. Under Infrastructure Secrets Management, select Other.
4. Select Create a Connect server.
5. Follow the onscreen instructions to create a 1password-credentials.json file and Connect token.

1Password CLI

You can use the 1Password CLI op connect command to set up a Secrets Automation workflow with a Connect server.

1. Make sure you have the latest version of 1Password CLI 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.

   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.

   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).

4. Create a token for the Connect server using the op connect token create command.

   tip

   Looking up a Connect server by its ID is more efficient than using the Connect server's name. See Unique identifiers (IDs).

   You can find the ID of a Connect server by running op 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. You can issue additional tokens later.

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.

tip

Export your Connect server token as an environment variable. Doing so might prove useful if you decide to configure another tool like the Kubernetes Injector, Kubernetes 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.

Step 2: Deploy 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 serves the Connect server REST API.
• 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 for more information.

1. Make sure you have Docker and Docker Compose 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 .

   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 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 for more information.

3. Make sure Docker is running. You can check if the Docker daemon 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.

   tip

   You can run the containers in the background using the -detach flag or the -d flag. Refer to the docker compose up reference 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 for more information.

Test the Connect Server REST API

You can make sure the Connect server REST API is accessible using a curl command, one of the 1Password Connect server API endpoints, and the token you created.

1. Export the Connect server token as an environment variable. This is the same token you created in 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.

2. Use the following example curl command to list the vaults connected to the Connect server.

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.

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 or use the Play with Kubernetes playground.

1. Make sure you have Docker installed and running on your machine.

2. Install the latest Helm release.

3. Add the 1Password Helm chart repository.

   The following command adds the 1Password Helm chart repository to your local instance of Helm. This allows you to download and install all the charts from 1Password's GitHub repository.

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.

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 on 1Password's GitHub that uses cert-manager to provision a TLS (transport layer security) certificate for an external domain.

Deploy alongside the Kubernetes Operator

The 1Password Connect Kubernetes Operator integrates Kubernetes Secrets with 1Password. It also auto-restarts deployments when 1Password items are updated. Learn more about the Kubernetes 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 for each application or service you use.

Languages

Go

Node.js

Python

Plugins

Terraform provider

Kubernetes integrations

Hashicorp Vault backend

Ansible collection

If your language or platform isn't listed, you can build your own client using the 1Password Connect Server REST API.

You can also use 1Password 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.

To get help and share feedback, join the discussion with the 1Password Support Community.