1password Secrets

---
name: 1password-secrets
description: "Expert agent for 1Password Secrets Automation. Covers service accounts, Connect Server (self-hosted bridge), SDKs (Node.js, Python, Go), CLI (op), GitHub Actions integration, Terraform provider, and Kubernetes operator. WHEN: \"1Password\", \"1Password Connect\", \"1Password service account\", \"op CLI\", \"1Password SDK\", \"1Password Kubernetes\", \"1Password Terraform\", \"1Password GitHub Actions\"."
license: MIT
---

# 1Password Secrets Automation

This skill covers 1Password Secrets Automation for developer and infrastructure workflows. It has deep knowledge of service accounts, 1Password Connect, SDKs, the `op` CLI, and Kubernetes/CI/CD integrations.

## How to Approach Tasks

When you receive a request:

1. **Classify** the request:
   - **Service account setup** — Service account creation and token management
   - **Connect Server** — Self-hosted bridge deployment and configuration
   - **SDK integration** — Node.js, Python, Go, Ruby SDK patterns
   - **CLI usage** — `op` CLI scripting and automation
   - **CI/CD** — GitHub Actions, GitLab, Jenkins integration
   - **Kubernetes** — 1Password operator patterns
   - **Terraform** — Provider configuration and usage
   - **Access control** — Vault permissions, item sharing

2. **Identify integration method** — Service accounts (direct API) vs. Connect Server (self-hosted proxy).

## Key Concepts

### 1Password Vaults

1Password organizes secrets in **Vaults**. Vault permissions control who (or what service account) can access which items.

Items in a vault:
- **Login**: username + password + website
- **Secure Note**: free-form text
- **Database**: DB connection fields
- **API Credential**: API key + other fields
- Custom categories

For automation, reference specific fields within items using references:
```
op://VaultName/ItemTitle/FieldName
op://VaultName/ItemTitle/section/FieldName
```

### Service Accounts

Service accounts provide non-interactive access to 1Password for automation. They have:
- A service account token (SA token, starts with `ops_`)
- Vault-level permissions (read-only or read-write on specific vaults)
- No 2FA requirement (suitable for automation)

```bash
# Create a service account (requires 1Password CLI as owner/admin)
op service-account create "Production Deployment" \
    --expires-in 8760h \
    --vault "Production" read

# Token is shown once — store it securely
# OP_SERVICE_ACCOUNT_TOKEN=ops_xxxxxxxxxxxxxxxx
```

### 1Password Connect Server

Connect is a self-hosted HTTP API server that acts as a proxy between your infrastructure and 1Password:
- Deploy in your infrastructure (Docker, Kubernetes)
- Applications call Connect's REST API instead of 1Password cloud API
- Connect uses a Connect token (different from service account token)
- Enables air-gapped or compliance-restricted environments

```
Application → Connect Server (on-prem/cloud) → 1Password Cloud
```

## CLI (op)

### Installation

```bash
# macOS
brew install 1password-cli

# Linux
curl -sSfo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.30.0/op_linux_amd64_v2.30.0.zip
unzip op.zip -d /usr/local/bin/

# Windows (scoop)
scoop install 1password-cli
```

### Authentication

```bash
# Interactive sign-in (stores session in keychain)
op signin

# Service account auth (non-interactive)
export OP_SERVICE_ACCOUNT_TOKEN=ops_xxxxxxxxxxxxxxxxxx

# Connect Server auth
export OP_CONNECT_HOST=https://connect.example.com
export OP_CONNECT_TOKEN=xxxxxxxxxxxxxxxx
```

### Common Operations

```bash
# Read a secret field
op read "op://Production/MyApp Config/db_password"

# Inject secrets into environment and run command
op run --env-file=".env.1p" -- node server.js

# .env.1p format:
# DB_PASSWORD=op://Production/MyApp Config/db_password
# API_KEY=op://Production/MyApp Config/api_key

# Get item as JSON
op item get "MyApp Config" --vault Production --format json

# List all vaults
op vault list --format json

# List items in a vault
op item list --vault Production --format json

# Create an item
op item create \
    --category "API Credential" \
    --title "New Service Key" \
    --vault Production \
    "credential[password]=my-api-key"

# Edit an item field
op item edit "MyApp Config" --vault Production "db_password=new-password"
```

### Scripting with op inject

```bash
# Template file: config.tmpl
# DB_PASSWORD={{ op://Production/DB Credentials/password }}
# API_URL={{ op://Production/MyApp Config/api_url }}

# Inject secrets into template
op inject -i config.tmpl -o config.env

# Or use process substitution
source <(op inject -i config.tmpl)
```

## SDKs

### Node.js / TypeScript

```typescript
import { OnePasswordConnect } from "@1password/connect";
// Or with service account:
import { createClient } from "@1password/sdk";

// Service Account SDK (newer, recommended)
const client = await createClient({
    auth: process.env.OP_SERVICE_ACCOUNT_TOKEN,
    integrationName: "My App",
    integrationVersion: "v1.0.0",
});

// Read a secret
const secret = await client.secrets.resolve("op://Production/MyApp Config/db_password");

// List vaults
const vaults = await client.vaults.listAll();

// Get item
const item = await client.items.get("vault-id", "item-id");
```

### Python

```python
import onepassword

client = onepassword.Client(
    auth=os.environ["OP_SERVICE_ACCOUNT_TOKEN"],
    integration_name="My App",
    integration_version="v1.0.0",
)

# Resolve a secret reference
password = client.secrets.resolve("op://Production/DB Credentials/password")

# Get a full item
item = client.items.get(vault_id="vault-id", item_id="item-id")
```

### Go

```go
import "github.com/1password/onepassword-sdk-go"

client, err := onepassword.NewClient(
    ctx,
    onepassword.WithServiceAccountToken(os.Getenv("OP_SERVICE_ACCOUNT_TOKEN")),
    onepassword.WithIntegrationInfo("My App", "v1.0.0"),
)

secret, err := client.Secrets.Resolve(ctx, "op://Production/MyApp Config/db_password")
```

## Connect Server Deployment

### Docker

```yaml
# docker-compose.yml
version: "3.8"
services:
  connect-api:
    image: 1password/connect-api:latest
    ports:
      - "8080:8080"
    volumes:
      - /path/to/credentials.json:/home/opuser/.op/1password-credentials.json
    environment:
      OP_SESSION: <connect-credentials-file-token>

  connect-sync:
    image: 1password/connect-sync:latest
    volumes:
      - /path/to/credentials.json:/home/opuser/.op/1password-credentials.json
    environment:
      OP_SESSION: <connect-credentials-file-token>
```

### Kubernetes

```bash
helm repo add 1password https://1password.github.io/connect-helm-charts
helm install connect 1password/connect \
    --namespace 1password \
    --create-namespace \
    --set-file connect.credentials=/path/to/1password-credentials.json \
    --set operator.create=true \
    --set operator.token.value=<op-connect-token>
```

## Kubernetes Operator

The 1Password Operator syncs items into Kubernetes Secrets:

```yaml
# OnePasswordItem resource
apiVersion: onepassword.com/v1
kind: OnePasswordItem
metadata:
  name: myapp-db-credentials
  namespace: production
spec:
  itemPath: "vaults/Production/items/MyApp DB Credentials"
```

The operator creates a Kubernetes Secret named `myapp-db-credentials` with fields mapped from the 1Password item.

Auto-restart deployments on secret change:

```yaml
spec:
  template:
    metadata:
      annotations:
        operator.1password.io/auto-restart: "true"
```

## GitHub Actions Integration

### Using Service Account Token

```yaml
# .github/workflows/deploy.yml
name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Load secrets from 1Password
      uses: 1password/load-secrets-action@v2
      with:
        export-env: true
      env:
        OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
        DB_PASSWORD: op://Production/DB Credentials/password
        API_KEY: op://Production/API Keys/stripe_key
    
    - name: Deploy (secrets available as env vars)
      run: ./deploy.sh
```

## Terraform Provider

```hcl
terraform {
  required_providers {
    onepassword = {
      source  = "1Password/onepassword"
      version = "~> 2.0"
    }
  }
}

provider "onepassword" {
  # Service account auth
  service_account_token = var.op_service_account_token
  
  # Or Connect Server auth
  # url   = "https://connect.example.com"
  # token = var.op_connect_token
}

# Read an item
data "onepassword_item" "db_credentials" {
  vault = "Production"
  title = "DB Credentials"
}

# Use field values
resource "aws_db_instance" "main" {
  username = data.onepassword_item.db_credentials.username
  password = data.onepassword_item.db_credentials.password
}

# Read specific field by reference
data "onepassword_item" "api_key" {
  vault = "Production"
  title = "API Keys"
}

output "stripe_key" {
  value     = data.onepassword_item.api_key.section["Payment"].field["stripe_key"].value
  sensitive = true
}
```

## Access Control and Best Practices

### Vault Structure for Teams

```
Organization
├── Production Vault
│   └── Access: Production Deploy SA (read), Platform Team (read/write)
├── Staging Vault
│   └── Access: Staging Deploy SA (read), All Engineers (read/write)
├── Development Vault
│   └── Access: All Engineers (read/write)
└── Shared Infrastructure
    └── Access: Infrastructure SA (read), Infra Team (read/write)
```

### Service Account Scoping

- One service account per deployment environment (not per application)
- Grant read-only access by default
- Set expiry dates on service account tokens (rotate annually)
- Use Connect Server for on-premises deployments to reduce direct internet dependency

### Secret References vs. Plaintext

Always use `op://` references in config files and scripts. Never copy secret values into environment configs, Helm values, or Terraform variables files that might be logged or stored in VCS.