### Install Yopass CLI

Source: https://yopass.se/docs/cli

Use the Go toolchain to install the latest version of the Yopass CLI.

```bash
go install github.com/jhaals/yopass/cmd/yopass@latest
```

--------------------------------

### Enable Yopass metrics

Source: https://yopass.se/docs/metrics

Start the Yopass server with a dedicated port for metrics collection.

```bash
yopass-server --metrics-port 9090
```

--------------------------------

### Start Yopass Services

Source: https://yopass.se/docs/quickstart

Execute this command to start the Yopass containers in detached mode.

```bash
docker compose up -d  
```

--------------------------------

### Configure File Size Limits

Source: https://yopass.se/docs/file-storage

Examples of setting the maximum file size using human-readable suffixes.

```bash
--max-file-size 10KB

--max-file-size 512KB

--max-file-size 10MB

--max-file-size 1.5GB
```

--------------------------------

### Enable Audit Logging

Source: https://yopass.se/docs/audit-logging

Use these flags to start the Yopass server with audit logging enabled.

```bash
yopass-server \  

  --license-key "your-license-key" \  

  --audit-log  
```

```bash
yopass-server \  

  --license-key    "your-license-key" \  

  --audit-log \  

  --audit-log-file /var/log/yopass/audit.log  
```

--------------------------------

### Configure MinIO for Yopass

Source: https://yopass.se/docs/file-storage

Commands to run a MinIO container, create a bucket, and start Yopass using the MinIO instance as the storage backend.

```bash
docker run -d \

  -p 9000:9000 \

  -e MINIO_ROOT_USER=minioadmin \

  -e MINIO_ROOT_PASSWORD=minioadmin \

  minio/minio server /data

  

# Create the bucket

mc alias set local http://localhost:9000 minioadmin minioadmin

mc mb local/yopass-files

  

# Start Yopass

AWS_ACCESS_KEY_ID=minioadmin \

AWS_SECRET_ACCESS_KEY=minioadmin \

yopass-server \

  --file-store              s3 \

  --file-store-s3-bucket    yopass-files \

  --file-store-s3-endpoint  http://localhost:9000 \

  --file-store-s3-region    us-east-1
```

--------------------------------

### Configure Yopass Server Instances

Source: https://yopass.se/docs/read-only-mode

Commands to start internal and public Yopass server instances with specific authentication and read-only flags.

```bash
# Internal instance — requires sign-in to create secrets  

yopass-server \  

  --license-key        "your-license-key" \  

  --oidc-issuer        "https://accounts.google.com" \  

  --oidc-client-id     "..." \  

  --oidc-client-secret "..." \  

  --oidc-redirect-url  "https://internal.example.com/auth/callback" \  

  --require-auth  

  

# Public instance — read-only, no authentication  

yopass-server \  

  --read-only \  

  --memcached memcached:11211
```

--------------------------------

### Start Yopass with S3 Storage

Source: https://yopass.se/docs/file-storage

Command to launch the Yopass server with S3 storage enabled and the built-in cleanup goroutine disabled.

```bash
yopass-server \

  --file-store              s3 \

  --file-store-s3-bucket    my-yopass-bucket \

  --disable-file-cleanup
```

--------------------------------

### Run Yopass Server with OIDC

Source: https://yopass.se/docs/openid-connect

Start the Yopass server using CLI flags or environment variables. The server requires connectivity to the OIDC provider's discovery document at startup.

```bash
yopass-server \
  --license-key   "your-license-key" \
  --oidc-issuer   "https://accounts.google.com" \
  --oidc-client-id     "123456789-abc.apps.googleusercontent.com" \
  --oidc-client-secret "GOCSPX-…" \
  --oidc-redirect-url  "https://yopass.example.com/auth/callback"
```

```bash
LICENSE_KEY=your-license-key \
OIDC_ISSUER=https://accounts.google.com \
OIDC_CLIENT_ID=123456789-abc.apps.googleusercontent.com \
OIDC_CLIENT_SECRET=GOCSPX-… \
OIDC_REDIRECT_URL=https://yopass.example.com/auth/callback \
yopass-server
```

--------------------------------

### Docker Compose Split Deployment

Source: https://yopass.se/docs/read-only-mode

Example configuration for running internal and public Yopass instances sharing a Memcached backend.

```yaml
services:  

  yopass-internal:  

    image: jhaals/yopass:latest  

    ports:  

      - "127.0.0.1:1337:1337"  # accessible only from localhost / VPN  

    environment:  

      MEMCACHED: memcached:11211  

    depends_on:  

      - memcached  

  

  yopass-public:  

    image: jhaals/yopass:latest  

    ports:  

      - "0.0.0.0:1338:1337"    # public-facing  

    environment:  

      MEMCACHED: memcached:11211  

      READ_ONLY: "true"  

    depends_on:  

      - memcached  

  

  memcached:  

    image: memcached
```

--------------------------------

### Configure Yopass Server Webhooks

Source: https://yopass.se/docs/webhooks

Use these flags when starting the yopass-server to enable event notifications. A valid license key is required for webhook functionality.

```bash
yopass-server \
  --license-key "your-license-key" \
  --webhook-url "https://hooks.example.com/yopass" \
  --webhook-secret "$(openssl rand -hex 32)"
```

--------------------------------

### Common Yopass CLI Usage Examples

Source: https://yopass.se/docs/cli

Standard commands for encrypting secrets, sharing files, and decrypting existing Yopass URLs.

```bash
# Encrypt and share a secret from stdin  

printf 'secret message' | yopass  

  

# Encrypt and share a file  

yopass --file /path/to/secret.conf  

  

# Share a secret that can be downloaded multiple times for one day  

cat secret-notes.md | yopass --expiration=1d --one-time=false  

  

# Decrypt a secret to stdout  

yopass --decrypt https://yopass.se/#/...
```

--------------------------------

### Deploy Yopass with Let's Encrypt via Docker Compose

Source: https://yopass.se/docs/tls

Commands to navigate to the deployment directory and start the Yopass service with Nginx proxy and Let's Encrypt.

```bash
cd deploy/with-nginx-proxy-and-letsencrypt  

# Edit docker-compose.yml and set VIRTUAL_HOST, LETSENCRYPT_HOST, LETSENCRYPT_EMAIL  

docker-compose up -d  
```

--------------------------------

### Audit Log Event Examples

Source: https://yopass.se/docs/audit-logging

Sample NDJSON records for various security events.

```json
{"timestamp":"2026-04-09T12:00:01.123456789Z","event":"secret.created","outcome":"success","client_ip":"203.0.113.42","secret_id":"k9bXz3mQ2vR7nLpA4wEy5a","one_time":true,"expiration_seconds":3600,"require_auth":false,"user_email":"alice@corp.example","user_subject":"auth0|abc123"}  
```

```json
{"timestamp":"2026-04-09T12:01:00.000000001Z","event":"secret.accessed","outcome":"denied","client_ip":"198.51.100.7","secret_id":"k9bXz3mQ2vR7nLpA4wEy5a","require_auth":true,"error":"authentication required"}  
```

```json
{"timestamp":"2026-04-09T12:00:00.500000000Z","event":"auth.callback_success","outcome":"success","client_ip":"203.0.113.42","user_email":"alice@corp.example","user_subject":"auth0|abc123"}  
```

--------------------------------

### Enable Audit Logging with OIDC

Source: https://yopass.se/docs/audit-logging

Starts the Yopass server with audit logging and OIDC authentication to include user identity in logs.

```bash
yopass-server \  

  --license-key        "your-license-key" \  

  --audit-log \  

  --oidc-issuer        "https://accounts.google.com" \  

  --oidc-client-id     "123456789-abc.apps.googleusercontent.com" \  

  --oidc-client-secret "GOCSPX-…" \  

  --oidc-redirect-url  "https://yopass.example.com/auth/callback"
```

--------------------------------

### Enable secret requests via CLI

Source: https://yopass.se/docs/secret-requests

Start the Yopass server with a valid license key to enable the secret requests feature.

```bash
yopass-server --license-key "your-license-key"  
```

--------------------------------

### Enable Read-Only Mode

Source: https://yopass.se/docs/read-only-mode

Start the Yopass server with the read-only flag to disable creation endpoints.

```bash
yopass-server --read-only
```

--------------------------------

### Deploy Yopass with OIDC via Docker Compose

Source: https://yopass.se/docs/openid-connect

Example configuration for running Yopass and Memcached using Docker Compose with OIDC authentication enabled.

```yaml
services:  

  yopass:  

    image: jhaals/yopass:latest  

    ports:  

      - "1337:1337"  

    environment:  

      MEMCACHED: memcached:11211  

      LICENSE_KEY: your-license-key  

      OIDC_ISSUER: https://accounts.google.com  

      OIDC_CLIENT_ID: 123456789-abc.apps.googleusercontent.com  

      OIDC_CLIENT_SECRET: GOCSPX-…  

      OIDC_REDIRECT_URL: https://yopass.example.com/auth/callback  

      REQUIRE_AUTH: "true"  

      OIDC_ALLOWED_DOMAINS: example.com  # optional: comma-separated list of allowed email domains  

      OIDC_SESSION_KEY: 3f2a1b…c9d8e7   # required for replicated deployments  

    depends_on:  

      - memcached  

  

  memcached:  

    image: memcached  
```

--------------------------------

### Webhook Payload Example

Source: https://yopass.se/docs/webhooks

The structure of the JSON body delivered in each webhook POST request.

```json
{

  "event": "secret.viewed",

  "timestamp": "2026-06-11T13:37:00.000000042Z",

  "secret_id": "a1b2c3d4e5f6",

  "kind": "secret",

  "one_time": true,

  "expiration_seconds": 3600

}
```

--------------------------------

### GET /request/<id>

Source: https://yopass.se/docs/secret-requests

Checks the current state of a secret request.

```APIDOC
## GET /request/<id>

### Description
Retrieves the state of a specific request. Polling this endpoint allows integrations to detect when a request is fulfilled.

### Method
GET

### Endpoint
https://yopass.example.com/request/<id>

### Parameters
#### Path Parameters
- **id** (string) - Required - The request ID

### Response
#### Success Response (200)
- **public_key** (string) - PGP public key block
- **label** (string) - Request label
- **state** (string) - Request state (pending or fulfilled)
- **expires_at** (integer) - Unix timestamp of expiration
```

--------------------------------

### GET /request/<id>/secret

Source: https://yopass.se/docs/secret-requests

Retrieves the secret associated with a request.

```APIDOC
## GET /request/<id>/secret

### Description
Retrieves the secret and deletes the request from the server. Requires the request token.

### Method
GET

### Endpoint
https://yopass.example.com/request/<id>/secret

### Parameters
#### Path Parameters
- **id** (string) - Required - The request ID

### Headers
- **X-Yopass-Request-Token** (string) - Required - Authorization token
```

--------------------------------

### GET /secret/<id>/receipt

Source: https://yopass.se/docs/read-receipts

Checks the status of a read receipt for a secret or file.

```APIDOC
## GET /secret/<id>/receipt

### Description
Checks the current status of a read receipt. Requires the receipt_token provided during creation.

### Method
GET

### Endpoint
https://yopass.example.com/secret/<id>/receipt

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the secret or file.

#### Query Parameters
- **X-Yopass-Receipt-Token** (string) - Required - The receipt token obtained during creation.

### Response
#### Success Response (200)
- **state** (string) - The current state (e.g., 'pending', 'viewed').
- **one_time** (boolean) - Whether the secret is one-time use.
- **created_at** (integer) - Creation timestamp.
- **expires_at** (integer) - Expiration timestamp.
- **viewed_at** (integer) - Optional - Timestamp when the secret was viewed.
```

--------------------------------

### Build with Custom Defaults

Source: https://yopass.se/docs/cli

Embed custom API and URL defaults directly into the binary at build time using linker flags.

```bash
go build -ldflags "-X main.defaultAPI=https://api.example.com -X main.defaultURL=https://example.com" \

  github.com/jhaals/yopass/cmd/yopass
```

--------------------------------

### Configure Custom Server Instance

Source: https://yopass.se/docs/cli

Methods for pointing the CLI to a self-hosted Yopass instance via command flags or configuration files.

```bash
printf 'secret' | yopass --api https://api.example.com --url https://example.com
```

```yaml
api: https://api.example.com  

url: https://example.com
```

--------------------------------

### Run Yopass with Database Backend

Source: https://yopass.se/docs/file-storage

The default backend stores files in Memcached or Redis. Note that Memcached has a 1MB item size limit.

```bash
yopass-server  # file-store defaults to the database backend  
```

--------------------------------

### Configure Built-in TLS

Source: https://yopass.se/docs/tls

Pass the certificate and private key paths to the yopass-server command to enable HTTPS.

```bash
yopass-server \  

  --tls-cert /etc/ssl/yopass/tls.crt \  

  --tls-key  /etc/ssl/yopass/tls.key  
```

--------------------------------

### Configure Application Name

Source: https://yopass.se/docs/theming

Replace the default Yopass branding in the UI header and browser tab.

```bash
yopass-server --app-name "Acme Secrets" --license-key "your-license-key"
```

--------------------------------

### Apply S3 Lifecycle Configuration via CLI

Source: https://yopass.se/docs/file-storage

Command to apply the lifecycle configuration file to a specific S3 bucket.

```bash
aws s3api put-bucket-lifecycle-configuration \

  --bucket my-yopass-bucket \

  --lifecycle-configuration file://lifecycle.json
```

--------------------------------

### Split Deployment Architecture Diagram

Source: https://yopass.se/docs/read-only-mode

Visual representation of the split deployment pattern using a shared database.

```text
[Employee] ──► internal.example.com (normal mode, behind VPN)

                      │  

                      ▼  

                  [Memcached / Redis]

                      │  

                      ▼  

[Recipient] ──► yopass.example.com (read-only, public)
```

--------------------------------

### Configure machine-to-machine API tokens

Source: https://yopass.se/docs/openid-connect

Generate a secure token and configure the server to accept it for automated secret creation.

```bash
# Generate a strong secret (minimum 16 characters enforced)  

openssl rand -hex 32  

  

yopass-server \

  --require-auth \

  --api-token "cmdb:4f6a…9c2e" \

  # … other OIDC flags
```

--------------------------------

### Configure custom logo via CLI

Source: https://yopass.se/docs/theming

Use the --logo-url flag to specify a custom logo path. Requires a valid --license-key.

```bash
yopass-server \

  --license-key "your-license-key" \

  --logo-url    "/mylogo.png"
```

--------------------------------

### Enable read receipts via command-line

Source: https://yopass.se/docs/read-receipts

Use the --license-key flag to enable read receipts on the Yopass server.

```bash
yopass-server --license-key "your-license-key"
```

--------------------------------

### Run Yopass with S3 Backend

Source: https://yopass.se/docs/file-storage

Configures storage for AWS S3 or S3-compatible services like MinIO or R2. Credentials are loaded via the standard AWS chain.

```bash
# AWS S3  

yopass-server \  

  --file-store            s3 \  

  --file-store-s3-bucket  my-yopass-bucket  

  

# S3-compatible (MinIO, Cloudflare R2, etc.)  

yopass-server \  

  --file-store              s3 \  

  --file-store-s3-bucket    my-bucket \  

  --file-store-s3-endpoint  http://minio:9000 \  

  --file-store-s3-region    us-east-1  
```

--------------------------------

### Configure Frontend URL for OIDC

Source: https://yopass.se/docs/read-only-mode

Command to set the frontend URL when the internal instance URL differs from the OIDC redirect target.

```bash
yopass-server \  

  --oidc-redirect-url "https://api.internal.example.com/auth/callback" \  

  --frontend-url      "https://internal.example.com"
```

--------------------------------

### Build custom Docker image with logo

Source: https://yopass.se/docs/theming

Copy the logo file into the public directory of the Docker image to serve it locally.

```dockerfile
FROM jhaals/yopass:latest

COPY mylogo.png /public/mylogo.png
```

--------------------------------

### Run custom Docker container

Source: https://yopass.se/docs/theming

Execute the custom image with the logo URL flag pointing to the internal path.

```bash
docker build -t yopass-custom .

docker run -p 1337:1337 yopass-custom \

  --license-key your-license-key \

  --logo-url /mylogo.png
```

--------------------------------

### Deploy Yopass with Metrics via Docker Compose

Source: https://yopass.se/docs/metrics

Full stack configuration including Yopass, Memcached, Prometheus, and Grafana. Ensure the metrics port is restricted in production environments.

```yaml
services:  

  yopass:  

    image: jhaals/yopass:latest  

    ports:  

      - "1337:1337"  

      - "9090:9090"   # metrics — restrict this in production  

    environment:  

      MEMCACHED: memcached:11211  

      METRICS_PORT: "9090"  

    depends_on:  

      - memcached  

  

  memcached:  

    image: memcached  

  

  prometheus:  

    image: prom/prometheus  

    volumes:  

      - ./prometheus.yml:/etc/prometheus/prometheus.yml  

    ports:  

      - "9091:9090"  

  

  grafana:  

    image: grafana/grafana  

    ports:  

      - "3000:3000"  

    depends_on:  

      - prometheus  
```

--------------------------------

### POST /create/file

Source: https://yopass.se/docs/read-receipts

Creates a file upload with a read receipt enabled using headers for configuration.

```APIDOC
## POST /create/file

### Description
Uploads a file with read receipt tracking enabled via custom headers.

### Method
POST

### Endpoint
https://yopass.example.com/create/file

### Parameters
#### Query Parameters
- **X-Yopass-Expiration** (integer) - Optional - Expiration time in seconds.
- **X-Yopass-OneTime** (boolean) - Optional - Whether the file is one-time use.
- **X-Yopass-Receipt** (boolean) - Optional - Enable read receipt tracking.

### Response
#### Success Response (200)
- **receipt_token** (string) - Token used to check the receipt status.
```

--------------------------------

### Generate a 64-byte session key

Source: https://yopass.se/docs/openid-connect

Use OpenSSL to generate a secure, random 64-byte key for session encryption.

```bash
# Generate once and store securely  

openssl rand -hex 64  

# → e.g. 3f2a1b…c9d8e7  (128 hex characters)  
```

--------------------------------

### Create a file upload with a read receipt

Source: https://yopass.se/docs/read-receipts

Request a file receipt by including the X-Yopass-Receipt header in the upload request.

```bash
curl -X POST https://yopass.example.com/create/file \

  -H 'Content-Type: application/octet-stream' \

  -H 'X-Yopass-Expiration: 86400' \

  -H 'X-Yopass-OneTime: true' \

  -H 'X-Yopass-Receipt: true' \

  --data-binary @encrypted.bin
```

--------------------------------

### Set Built-in Themes

Source: https://yopass.se/docs/theming

Define light and dark themes using DaisyUI presets. The active theme is determined by the browser's prefers-color-scheme.

```bash
yopass-server \  
  --license-key   "your-license-key" \  
  --theme-light   "corporate" \  
  --theme-dark    "business"
```

--------------------------------

### Run Yopass with Docker and Built-in TLS

Source: https://yopass.se/docs/tls

Mount certificate volumes to the container and provide paths to the server flags.

```bash
docker run -p 443:1337 \  

  -v /etc/letsencrypt/live/yopass.example.com:/certs:ro \  

  jhaals/yopass:latest \  

  --memcached memcached:11211 \  

  --tls-cert /certs/fullchain.pem \  

  --tls-key  /certs/privkey.pem  
```

--------------------------------

### Apply Custom Themes

Source: https://yopass.se/docs/theming

Override design tokens using a JSON object of CSS variables. Values must use the oklch color format.

```bash
yopass-server \  
  --license-key         "your-license-key" \  
  --theme-custom-light  '{"--color-primary":"oklch(55% 0.2 250)","--color-secondary":"oklch(70% 0.15 180)"}' \  
  --theme-custom-dark   '{"--color-primary":"oklch(65% 0.25 260)","--color-secondary":"oklch(60% 0.18 190)"}'
```

```bash
yopass-server \  
  --license-key        "your-license-key" \  
  --theme-light        "corporate" \  
  --theme-custom-light '{"--color-primary":"oklch(50% 0.22 142)"}'
```

--------------------------------

### Configure Yopass for Reverse Proxy

Source: https://yopass.se/docs/tls

Run Yopass on localhost to allow a reverse proxy to handle TLS termination.

```bash
yopass-server --address 127.0.0.1 --port 1337  
```

--------------------------------

### Configure Yopass with Disk Storage in Docker Compose

Source: https://yopass.se/docs/file-storage

Uses a local volume to persist files on the host machine. Requires defining a volume and setting the FILE_STORE environment variable to disk.

```yaml
services:  

  yopass:  

    image: jhaals/yopass:latest  

    ports:  

      - "1337:1337"  

    volumes:  

      - yopass-files:/data/yopass-files  

    environment:  

      MEMCACHED: memcached:11211  

      FILE_STORE: disk  

      FILE_STORE_PATH: /data/yopass-files  

      MAX_FILE_SIZE: 50MB  

    depends_on:  

      - memcached  

  

  memcached:  

    image: memcached  

  

volumes:  

  yopass-files:  
```

--------------------------------

### Caddy Reverse Proxy Configuration

Source: https://yopass.se/docs/tls

Caddy automatically handles certificate provisioning for the specified domain.

```caddy
yopass.example.com {  

    reverse_proxy 127.0.0.1:1337  

}  
```

--------------------------------

### Enable Argon2 key derivation

Source: https://yopass.se/docs/server-options

Switch the S2K function to Argon2id using either a command-line flag or an environment variable.

```bash
yopass-server --argon2

# or via environment variable
ARGON2=true yopass-server
```

--------------------------------

### Run Yopass with Disk Backend

Source: https://yopass.se/docs/file-storage

Stores files as encrypted blobs on the local filesystem. A background process automatically cleans up expired files.

```bash
yopass-server \  

  --file-store      disk \  

  --file-store-path /data/yopass-files  
```

--------------------------------

### Obtain Certificates for Yopass

Source: https://yopass.se/docs/tls

Commands for generating certificates using Certbot or OpenSSL for development.

```bash
certbot certonly --standalone -d yopass.example.com  

  

yopass-server \  

  --tls-cert /etc/letsencrypt/live/yopass.example.com/fullchain.pem \  

  --tls-key  /etc/letsencrypt/live/yopass.example.com/privkey.pem  
```

```bash
openssl req -x509 -nodes -newkey rsa:4096 \  

  -keyout tls.key -out tls.crt \  

  -days 365 -subj "/CN=localhost"  

  

yopass-server --tls-cert tls.crt --tls-key tls.key  
```

--------------------------------

### Configure Yopass with Redis

Source: https://yopass.se/docs/quickstart

Use this Docker Compose configuration to run Yopass with a Redis storage backend.

```yaml
services:  

  yopass:  

    image: jhaals/yopass:latest  

    ports:  

      - "1337:1337"  

    environment:  

      DATABASE: redis  

      REDIS: redis://redis:6379/0  

    depends_on:  

      - redis  

  

  redis:  

    image: redis:7-alpine  
```

--------------------------------

### Configure Yopass with Docker Compose

Source: https://yopass.se/docs/theming

Defines the Yopass service and its dependencies, including theme and branding environment variables.

```yaml
services:  

  yopass:  

    image: jhaals/yopass:latest  

    ports:  

      - "1337:1337"  

    environment:  

      MEMCACHED: memcached:11211  

      LICENSE_KEY: your-license-key  

      APP_NAME: Acme Secrets  

      THEME_LIGHT: corporate  

      THEME_DARK: business  

      THEME_CUSTOM_LIGHT: '{"--color-primary":"oklch(55% 0.2 250)"}'  

      LOGO_URL: /mylogo.svg  

    depends_on:  

      - memcached  

  

  memcached:  

    image: memcached
```

--------------------------------

### Configure Content-Security-Policy for Argon2

Source: https://yopass.se/docs/server-options

Add the required CSP directive to your reverse proxy configuration to support Argon2 key derivation.

```text
Content-Security-Policy: ... script-src 'self' 'wasm-unsafe-eval'; ...
```

--------------------------------

### Configure Authorized Redirect URI

Source: https://yopass.se/docs/openid-connect

The callback URL required when creating an OAuth 2.0 client in the Google Cloud Console.

```text
https://yopass.example.com/auth/callback
```

--------------------------------

### Deploy Yopass with Docker Compose

Source: https://yopass.se/docs/read-only-mode

Docker Compose configuration for running both internal and public Yopass instances with OIDC and read-only settings.

```yaml
services:  

  yopass-internal:  

    image: jhaals/yopass:latest  

    ports:  

      - "127.0.0.1:1337:1337"  

    environment:  

      MEMCACHED: memcached:11211  

      LICENSE_KEY: your-license-key  

      OIDC_ISSUER: https://accounts.google.com  

      OIDC_CLIENT_ID: "123456789-abc.apps.googleusercontent.com"  

      OIDC_CLIENT_SECRET: "GOCSPX-..."  

      OIDC_REDIRECT_URL: https://internal.example.com/auth/callback  

      REQUIRE_AUTH: "true"  

      OIDC_ALLOWED_DOMAIN: example.com  

    depends_on:  

      - memcached  

  

  yopass-public:  

    image: jhaals/yopass:latest  

    ports:  

      - "0.0.0.0:1338:1337"  

    environment:  

      MEMCACHED: memcached:11211  

      READ_ONLY: "true"  

    depends_on:  

      - memcached  

  

  memcached:  

    image: memcached
```

--------------------------------

### Secure Metrics Endpoint with Nginx

Source: https://yopass.se/docs/metrics

Configure Nginx as a reverse proxy with basic authentication for the metrics endpoint.

```nginx
server {  

    listen 9090;  

    location /metrics {  

        auth_basic "Prometheus";  

        auth_basic_user_file /etc/nginx/.htpasswd;  

        proxy_pass http://127.0.0.1:9090;  

    }  

}
```

--------------------------------

### Configure Audit Logging to Stdout

Source: https://yopass.se/docs/audit-logging

Configures the application to output audit logs to stdout by omitting the file path variable.

```yaml
environment:  

  AUDIT_LOG: "true"  

  # no AUDIT_LOG_FILE — records go to stdout alongside application logs
```

--------------------------------

### Submit a secret

Source: https://yopass.se/docs/secret-requests

Fulfill a pending request by submitting a PGP-encrypted message.

```bash
curl -X POST https://yopass.example.com/request/<id>/secret \

  -H 'Content-Type: application/json' \

  -d '{"message": "-----BEGIN PGP MESSAGE----- ..."}'
```

--------------------------------

### Create a secret request

Source: https://yopass.se/docs/secret-requests

Submit a request for a secret by providing a PGP public key and expiration time.

```bash
curl -X POST https://yopass.example.com/request \

  -H 'Content-Type: application/json' \

  -d '{

    "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK----- ...",

    "label": "Production API key for ticket #4711",

    "expiration": 86400

  }'
```

```json
{

  "id": "5Hp2…",

  "token": "wXg9…",

  "expires_at": 1765465600

}
```

--------------------------------

### Configure Yopass with Memcached

Source: https://yopass.se/docs/quickstart

Use this Docker Compose configuration to run Yopass with a Memcached storage backend.

```yaml
services:  

  yopass:  

    image: jhaals/yopass:latest  

    ports:  

      - "1337:1337"  

    environment:  

      MEMCACHED: memcached:11211  

    depends_on:  

      - memcached  

  

  memcached:  

    image: memcached  
```

--------------------------------

### Disable Built-in Cleanup

Source: https://yopass.se/docs/file-storage

Command to run the Yopass server with the automatic file cleanup goroutine disabled.

```bash
yopass-server --disable-file-cleanup
```

--------------------------------

### Replace public key

Source: https://yopass.se/docs/secret-requests

Update the public key for a pending request.

```bash
curl -X PUT https://yopass.example.com/request/<id>/key \

  -H 'X-Yopass-Request-Token: <token>' \

  -H 'Content-Type: application/json' \

  -d '{"public_key": "-----BEGIN PGP PUBLIC KEY BLOCK----- ..."}'
```

--------------------------------

### Configure Audit Logging in Docker Compose

Source: https://yopass.se/docs/audit-logging

Defines a Yopass service with audit logging enabled and a volume mount for log persistence.

```yaml
services:  

  yopass:  

    image: jhaals/yopass:latest  

    ports:  

      - "1337:1337"  

    environment:  

      MEMCACHED: memcached:11211  

      LICENSE_KEY: your-license-key  

      AUDIT_LOG: "true"  

    volumes:  

      - ./logs:/var/log/yopass  

    command: >  

      yopass-server  

      --audit-log-file /var/log/yopass/audit.log  

    depends_on:  

      - memcached  

  

  memcached:  

    image: memcached
```

--------------------------------

### Secure Metrics Endpoint with Firewall

Source: https://yopass.se/docs/metrics

Restrict access to the metrics port using UFW rules.

```bash
ufw allow from 10.0.0.0/8 to any port 9090

ufw deny 9090
```

--------------------------------

### Configure OIDC session key for Yopass

Source: https://yopass.se/docs/openid-connect

Apply the generated session key to Yopass instances via command-line flags or environment variables to ensure session consistency.

```bash
yopass-server \  

  --oidc-session-key "3f2a1b…c9d8e7" \  

  # … other OIDC flags  
```

```bash
OIDC_SESSION_KEY=3f2a1b…c9d8e7 yopass-server …  
```

--------------------------------

### Configure logrotate for Yopass audit logs

Source: https://yopass.se/docs/audit-logging

Use this configuration in /etc/logrotate.d/yopass-audit to manage log rotation. The copytruncate directive ensures logs are truncated in place without requiring SIGHUP signals.

```text
/var/log/yopass/audit.log {  

    daily  

    rotate 90  

    compress  

    delaycompress  

    missingok  

    notifempty  

    copytruncate  

}  
```

--------------------------------

### Configure Yopass with S3 Storage in Docker Compose

Source: https://yopass.se/docs/file-storage

Configures Yopass to store files in an S3 bucket. Requires AWS credentials and region settings provided via environment variables.

```yaml
services:  

  yopass:  

    image: jhaals/yopass:latest  

    ports:  

      - "1337:1337"  

    environment:  

      MEMCACHED: memcached:11211  

      FILE_STORE: s3  

      FILE_STORE_S3_BUCKET: my-yopass-bucket  

      FILE_STORE_S3_REGION: eu-west-1  

      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}  

      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}  

      DISABLE_FILE_CLEANUP: "true"  # using S3 lifecycle rules instead  

    depends_on:  

      - memcached  

  

  memcached:  

    image: memcached  
```

--------------------------------

### Enforce Authentication for Secret Creation

Source: https://yopass.se/docs/openid-connect

Use the --require-auth flag to restrict secret creation to authenticated users. Secret retrieval remains accessible without authentication.

```bash
yopass-server \
  --license-key        "your-license-key" \
  --oidc-issuer        "https://accounts.google.com" \
  --oidc-client-id     "123456789-abc.apps.googleusercontent.com" \
  --oidc-client-secret "GOCSPX-…" \
  --oidc-redirect-url  "https://yopass.example.com/auth/callback" \
  --require-auth
```

--------------------------------

### POST /request

Source: https://yopass.se/docs/secret-requests

Creates a new secret request.

```APIDOC
## POST /request

### Description
Creates a new secret request with a specified public key and label.

### Method
POST

### Endpoint
https://yopass.example.com/request

### Request Body
- **public_key** (string) - Required - PGP public key block
- **label** (string) - Required - Description of the request
- **expiration** (integer) - Required - Expiration time in seconds (3600, 86400, or 604800)

### Response
#### Success Response (200)
- **id** (string) - Request ID
- **token** (string) - Authorization token for retrieval/revocation
- **expires_at** (integer) - Unix timestamp of expiration
```

--------------------------------

### Traefik Docker Compose Configuration

Source: https://yopass.se/docs/tls

Traefik configuration using labels to manage TLS and routing for Yopass.

```yaml
services:  

  traefik:  

    image: traefik:v3  

    command:  

      - "--providers.docker=true"  

      - "--entrypoints.web.address=:80"  

      - "--entrypoints.websecure.address=:443"  

      - "--certificatesresolvers.le.acme.email=admin@example.com"  

      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"  

      - "--certificatesresolvers.le.acme.tlschallenge=true"  

    ports:  

      - "80:80"  

      - "443:443"  

    volumes:  

      - /var/run/docker.sock:/var/run/docker.sock:ro  

      - letsencrypt:/letsencrypt  

  

  yopass:  

    image: jhaals/yopass:latest  

    environment:  

      MEMCACHED: memcached:11211  

    labels:  

      - "traefik.enable=true"  

      - "traefik.http.routers.yopass.rule=Host(`yopass.example.com`)"  

      - "traefik.http.routers.yopass.entrypoints=websecure"  

      - "traefik.http.routers.yopass.tls.certresolver=le"  

    depends_on:  

      - memcached  

  

  memcached:  

    image: memcached  

  

volumes:  

  letsencrypt:  
```

--------------------------------

### Grafana Dashboard Queries

Source: https://yopass.se/docs/metrics

PromQL queries for monitoring request rates, error rates, latency, goroutines, and memory usage in Grafana.

```PromQL
sum(rate(yopass_http_requests_total[1m])) by (handler)
```

```PromQL
sum(rate(yopass_http_requests_total{code=~"5.."}[1m])) by (handler)
```

```PromQL
histogram_quantile(0.95, sum(rate(yopass_http_request_duration_seconds_bucket[5m])) by (le, handler))
```

```PromQL
go_goroutines{job="yopass"}
```

```PromQL
process_resident_memory_bytes{job="yopass"}
```

--------------------------------

### Define Prometheus Alerting Rules

Source: https://yopass.se/docs/metrics

Alerting rules for Yopass covering high error rates, latency, and license expiration. Save as yopass-alerts.yml and reference in the Prometheus configuration.

```yaml
groups:  

  - name: yopass  

    rules:  

      - alert: YopassHighErrorRate  

        expr: |  

          sum(rate(yopass_http_requests_total{code=~"5.."}[5m]))  

          /  

          sum(rate(yopass_http_requests_total[5m])) > 0.05  

        for: 5m  

        labels:  

          severity: warning  

        annotations:  

          summary: "Yopass HTTP error rate above 5%"  

  

      - alert: YopassHighLatency  

        expr: |  

          histogram_quantile(0.95,  

            sum by (le, handler) (rate(yopass_http_request_duration_seconds_bucket[5m]))  

          ) > 2  

        for: 5m  

        labels:  

          severity: warning  

        annotations:  

          summary: "Yopass p95 latency above 2s on {{ $labels.handler }}"  

  

      - alert: YopassLicenseExpiringSoon  

        expr: yopass_license_days_until_expiry < 14  

        labels:  

          severity: warning  

        annotations:  

          summary: "Yopass license expires in {{ $value | humanizeDuration }}"  

  

      - alert: YopassLicenseExpired  

        expr: yopass_license_days_until_expiry < 0  

        labels:  

          severity: critical  

        annotations:  

          summary: "Yopass license has expired"  
```

--------------------------------

### Configure Prometheus Scrape Jobs

Source: https://yopass.se/docs/metrics

Define scrape targets for Yopass in prometheus.yml. Use the host address or container name depending on the deployment environment.

```yaml
scrape_configs:  

  - job_name: yopass  

    static_configs:  

      - targets: ["yopass-host:9090"]  
```

```yaml
scrape_configs:  

  - job_name: yopass  

    static_configs:  

      - targets: ["yopass:9090"]  
```

--------------------------------

### Configure S3 Lifecycle Rules

Source: https://yopass.se/docs/file-storage

JSON configuration for an S3 lifecycle rule to automatically expire objects older than 7 days.

```json
{

  "Rules": [

    {

      "ID": "yopass-expiration",

      "Filter": { "Prefix": "yopass/" },

      "Status": "Enabled",

      "Expiration": { "Days": 7 }

    }

  ]

}
```

--------------------------------

### Create a secret with a read receipt

Source: https://yopass.se/docs/read-receipts

Request a read receipt by setting the receipt field to true in the JSON payload.

```bash
curl -X POST https://yopass.example.com/create/secret \

  -H 'Content-Type: application/json' \

  -d '{

    "message": "-----BEGIN PGP MESSAGE----- ...",

    "expiration": 86400,

    "one_time": true,

    "receipt": true

  }'
```

```json
{

  "message": "8GjMyrJDkLwmnvKg9N1bzS",

  "receipt_token": "wXg9…"

}
```

--------------------------------

### Retrieve a secret

Source: https://yopass.se/docs/secret-requests

Fetch the secret using the request token. This action deletes the request from the server.

```bash
curl https://yopass.example.com/request/<id>/secret \

  -H 'X-Yopass-Request-Token: <token>'
```

--------------------------------

### Check the receipt status

Source: https://yopass.se/docs/read-receipts

Retrieve the status of a secret or file using the receipt token. The state will transition from pending to viewed once accessed.

```bash
curl https://yopass.example.com/secret/<id>/receipt \

  -H 'X-Yopass-Receipt-Token: <receipt_token>'
```

```json
{

  "state": "pending",

  "one_time": true,

  "created_at": 1765379200,

  "expires_at": 1765465600

}
```

```json
{

  "state": "viewed",

  "one_time": true,

  "created_at": 1765379200,

  "viewed_at": 1765380101,

  "expires_at": 1765465600

}
```

--------------------------------

### POST /create/secret

Source: https://yopass.se/docs/openid-connect

Creates a new secret using a bearer token for authentication.

```APIDOC
## POST /create/secret

### Description
Creates a new secret. This endpoint requires authentication via a bearer token when --require-auth is enabled.

### Method
POST

### Endpoint
/create/secret

### Request Body
- **message** (string) - Required - The secret message content.
- **expiration** (integer) - Optional - Expiration time in seconds.
- **one_time** (boolean) - Optional - Whether the secret is one-time use.

### Request Example
{
  "message": "-----BEGIN PGP MESSAGE-----",
  "expiration": 3600,
  "one_time": true
}
```

--------------------------------

### Authenticate API requests with a bearer token

Source: https://yopass.se/docs/openid-connect

Include the API token in the Authorization header when making requests to the creation endpoints.

```bash
curl https://yopass.example.com/create/secret \

  -H "Authorization: Bearer 4f6a…9c2e" \

  -H "Content-Type: application/json" \

  -d '{"message":"-----BEGIN PGP MESSAGE-----…","expiration":3600,"one_time":true}'
```

--------------------------------

### Verify Webhook Signatures

Source: https://yopass.se/docs/webhooks

Use these functions to authenticate incoming webhook requests by comparing the HMAC-SHA256 signature against the raw request body. Always use constant-time comparison functions to prevent timing attacks.

```python
import hashlib, hmac  

  

def verify(secret: str, body: bytes, signature_header: str) -> bool:  

    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()  

    return hmac.compare_digest(expected, signature_header)
```

```javascript
const crypto = require('crypto');  

  

function verify(secret, body, signatureHeader) {  

  const expected =  

    'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex');  

  return crypto.timingSafeEqual(  

    Buffer.from(expected),  

    Buffer.from(signatureHeader),  

  );  

}
```

--------------------------------

### PUT /request/<id>/key

Source: https://yopass.se/docs/secret-requests

Replaces the public key of a pending request.

```APIDOC
## PUT /request/<id>/key

### Description
Updates the public key for a request that is still in pending state.

### Method
PUT

### Endpoint
https://yopass.example.com/request/<id>/key

### Parameters
#### Path Parameters
- **id** (string) - Required - The request ID

### Headers
- **X-Yopass-Request-Token** (string) - Required - Authorization token

### Request Body
- **public_key** (string) - Required - New PGP public key block
```