pw-generator/integration-guide.md

Password Generator API Integration Guide

This guide provides comprehensive examples for integrating the Password Generator API with popular password managers, launchers, and automation tools.

Table of Contents

• Quick Start
• Password Managers
• Launchers & Tools
• Automation Scripts
• Security Considerations

Quick Start

The API provides several endpoints for password generation:

Base URL: http://localhost:8080/api/v1

Generate Password:

curl -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"diceware","count":1,"options":{"words":6}}'

Password Managers

Bitwarden

Bitwarden CLI Integration

Installation:

npm install -g @bitwarden/cli

Basic Password Generation and Storage:

#!/bin/bash
# generate-and-store-bitwarden.sh

# Login to Bitwarden (do this once)
bw login

# Unlock vault (enter master password when prompted)
export BW_SESSION="$(bw unlock --raw)"

# Generate high-entropy password
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"high-entropy","count":1,"options":{"length":20,"includeSymbols":true}}' | \
  jq -r '.data.passwords[0]')

# Create new login item
ITEM_DATA=$(cat <<EOF
{
  "type": 1,
  "name": "Generated Password $(date +%Y-%m-%d)",
  "login": {
    "username": "user@example.com",
    "password": "$PASSWORD"
  }
}
EOF
)

echo "$ITEM_DATA" | bw encode | bw create item

echo "Password created and stored in Bitwarden: $PASSWORD"

Advanced: Generate Different Password Types:

#!/bin/bash
# bitwarden-multi-generator.sh

generate_and_store() {
    local type=$1
    local name=$2
    local options=$3
    
    PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
      -H "Content-Type: application/json" \
      -d "{\"type\":\"$type\",\"count\":1,\"options\":$options}" | \
      jq -r '.data.passwords[0]')
    
    ITEM_DATA="{\"type\": 1, \"name\": \"$name\", \"login\": {\"password\": \"$PASSWORD\"}}"
    echo "$ITEM_DATA" | bw encode | bw create item
    
    echo "Created $name: $PASSWORD"
}

# Generate different types
generate_and_store "diceware" "Diceware Passphrase" '{"words":6,"capitalize":true}'
generate_and_store "passkey" "Apple-style Password" '{"syllables":4,"addNumbers":true}'
generate_and_store "xkcdpass" "XKCD Passphrase" '{"words":4,"language":"english","addNumber":true}'

1Password

1Password CLI Integration

Installation: Follow 1Password CLI installation guide for your platform.

Basic Integration:

#!/bin/bash
# generate-and-store-1password.sh

# Generate secure password
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"high-entropy","count":1,"options":{"length":24}}' | \
  jq -r '.data.passwords[0]')

# Create login item
op item create \
    --category=login \
    --title="Generated Password $(date +%Y-%m-%d)" \
    --field="username=user@example.com" \
    --field="password=$PASSWORD"

echo "Password stored in 1Password: $PASSWORD"

Batch Password Generation:

#!/bin/bash
# 1password-batch-generator.sh

TYPES=("diceware" "high-entropy" "passkey" "xkcdpass")
NAMES=("Diceware Phrase" "High Entropy" "Passkey Style" "XKCD Phrase")

for i in "${!TYPES[@]}"; do
    TYPE=${TYPES[$i]}
    NAME=${NAMES[$i]}
    
    PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
      -H "Content-Type: application/json" \
      -d "{\"type\":\"$TYPE\",\"count\":1}" | \
      jq -r '.data.passwords[0]')
    
    op item create \
        --category=login \
        --title="$NAME $(date +%Y-%m-%d)" \
        --field="password=$PASSWORD"
    
    echo "Created $NAME: $PASSWORD"
done

KeePass

KeePassXC CLI Integration

#!/bin/bash
# keepassxc-generator.sh

DB_PATH="$HOME/passwords.kdbx"
KEY_FILE="$HOME/keyfile.key"

# Generate password
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"diceware","count":1,"options":{"words":6}}' | \
  jq -r '.data.passwords[0]')

# Add to KeePass database
keepassxc-cli add "$DB_PATH" \
    --key-file "$KEY_FILE" \
    "Generated/$(date +%Y-%m-%d)" \
    --username "user@example.com" \
    --password-prompt

echo "Password: $PASSWORD"

Launchers & Tools

Raycast

Simple Password Generator Extension

Create a Raycast script command:

generate-password.sh:

#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Generate Secure Password  
# @raycast.mode compact
# @raycast.icon 🔐
# @raycast.packageName Password Generator
# @raycast.argument1 {"type": "dropdown", "placeholder": "Password Type", "data": [{"title": "High Entropy", "value": "high-entropy"}, {"title": "Diceware", "value": "diceware"}, {"title": "Passkey", "value": "passkey"}, {"title": "XKCD", "value": "xkcdpass"}]}

TYPE=${1:-"passkey"}

case $TYPE in
  "high-entropy")
    OPTIONS='{"length":16,"includeSymbols":true}'
    ;;
  "diceware")
    OPTIONS='{"words":5,"capitalize":true}'
    ;;
  "passkey")
    OPTIONS='{"syllables":3,"addNumbers":true}'
    ;;
  "xkcdpass")
    OPTIONS='{"words":4,"capitalize":true,"addNumber":true}'
    ;;
esac

PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"$TYPE\",\"count\":1,\"options\":$OPTIONS}" | \
  jq -r '.data.passwords[0]')

if [ -n "$PASSWORD" ]; then
    echo "$PASSWORD" | pbcopy
    echo "✅ Password copied: $PASSWORD"
else
    echo "❌ Failed to generate password"
fi

Advanced Raycast Extension with Options

raycast-advanced.sh:

#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Advanced Password Generator
# @raycast.mode fullOutput
# @raycast.icon 🔐
# @raycast.packageName Password Generator
# @raycast.argument1 {"type": "text", "placeholder": "Number of passwords", "optional": true}

COUNT=${1:-1}

# Generate multiple password types
echo "🔐 Password Generator Results"
echo "================================"

# High Entropy
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"high-entropy\",\"count\":$COUNT,\"options\":{\"length\":16}}" | \
  jq -r '.data.passwords[]' | head -1)
echo "🔒 High Entropy: $PASSWORD"

# Diceware
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"diceware\",\"count\":$COUNT,\"options\":{\"words\":5}}" | \
  jq -r '.data.passwords[]' | head -1)
echo "🎲 Diceware: $PASSWORD"

# Passkey
PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"passkey\",\"count\":$COUNT,\"options\":{\"syllables\":3}}" | \
  jq -r '.data.passwords[]' | head -1)
echo "🗝️  Passkey: $PASSWORD"

echo ""
echo "Select a password above to copy it."

Alfred

Alfred Workflow Script Filter

alfred-password-generator.php:

<?php
header('Content-Type: application/json');

$types = [
    'high-entropy' => ['name' => 'High Entropy', 'icon' => '🔒', 'options' => '{"length":16}'],
    'diceware' => ['name' => 'Diceware', 'icon' => '🎲', 'options' => '{"words":5}'],
    'passkey' => ['name' => 'Passkey', 'icon' => '🗝️', 'options' => '{"syllables":3}'],
    'xkcdpass' => ['name' => 'XKCD', 'icon' => '💭', 'options' => '{"words":4}']
];

$items = [];

foreach ($types as $type => $config) {
    $items[] = [
        'uid' => $type,
        'title' => $config['name'] . ' Password',
        'subtitle' => 'Generate ' . strtolower($config['name']) . ' password',
        'arg' => $type,
        'icon' => ['emoji' => $config['icon']]
    ];
}

echo json_encode(['items' => $items]);
?>

alfred-generate.sh:

#!/bin/bash
TYPE=$1

case $TYPE in
  "high-entropy")
    OPTIONS='{"length":16,"includeSymbols":true}'
    ;;
  "diceware")
    OPTIONS='{"words":5,"capitalize":true}'
    ;;
  "passkey")
    OPTIONS='{"syllables":3,"addNumbers":true}'
    ;;
  "xkcdpass")
    OPTIONS='{"words":4,"capitalize":true,"addNumber":true}'
    ;;
esac

PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d "{\"type\":\"$TYPE\",\"count\":1,\"options\":$OPTIONS}" | \
  jq -r '.data.passwords[0]')

echo "$PASSWORD" | pbcopy
echo "$PASSWORD"

LaunchBar

LaunchBar Action

PasswordGenerator.lbaction/Contents/Scripts/default.sh:

#!/bin/bash

PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"passkey","count":1,"options":{"syllables":4,"addNumbers":true}}' | \
  jq -r '.data.passwords[0]')

if [ -n "$PASSWORD" ]; then
    echo "$PASSWORD" | pbcopy
    echo "$PASSWORD"
else
    echo "Error generating password"
    exit 1
fi

Ubar / Menu Bar Apps

BitBar Plugin

password-generator.1m.sh:

#!/bin/bash

echo "🔐 Password Generator"
echo "---"

# Generate different types
TYPES=("high-entropy:High Entropy" "diceware:Diceware" "passkey:Passkey" "xkcdpass:XKCD")

for TYPE_PAIR in "${TYPES[@]}"; do
    TYPE="${TYPE_PAIR%%:*}"
    NAME="${TYPE_PAIR##*:}"
    
    PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
      -H "Content-Type: application/json" \
      -d "{\"type\":\"$TYPE\",\"count\":1}" | \
      jq -r '.data.passwords[0]' 2>/dev/null)
    
    if [ -n "$PASSWORD" ]; then
        echo "$NAME: $PASSWORD | bash='echo \"$PASSWORD\" | pbcopy' terminal=false"
    fi
done

echo "---"
echo "API Status | bash='curl -s http://localhost:8080/api/v1/health' terminal=true"

Automation Scripts

Automated Password Rotation

#!/bin/bash
# rotate-passwords.sh

SERVICES=("email:user@example.com" "bank:john.doe" "social:johndoe123")

for SERVICE_PAIR in "${SERVICES[@]}"; do
    SERVICE="${SERVICE_PAIR%%:*}"
    USERNAME="${SERVICE_PAIR##*:}"
    
    # Generate new password
    PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
      -H "Content-Type: application/json" \
      -d '{"type":"high-entropy","count":1,"options":{"length":20}}' | \
      jq -r '.data.passwords[0]')
    
    # Update in password manager (example with Bitwarden)
    ITEM_ID=$(bw list items --search "$SERVICE" | jq -r '.[0].id')
    if [ "$ITEM_ID" != "null" ]; then
        ITEM=$(bw get item "$ITEM_ID")
        UPDATED_ITEM=$(echo "$ITEM" | jq ".login.password = \"$PASSWORD\"")
        echo "$UPDATED_ITEM" | bw encode | bw edit item "$ITEM_ID"
        
        echo "Rotated password for $SERVICE: $PASSWORD"
    fi
done

Bulk Password Generation for Teams

#!/bin/bash
# team-password-generator.sh

TEAM_MEMBERS=("alice" "bob" "charlie" "diana")
SERVICES=("staging" "development" "testing")

for MEMBER in "${TEAM_MEMBERS[@]}"; do
    echo "Generating passwords for $MEMBER:"
    
    for SERVICE in "${SERVICES[@]}"; do
        PASSWORD=$(curl -s -X POST http://localhost:8080/api/v1/passwords/generate \
          -H "Content-Type: application/json" \
          -d '{"type":"diceware","count":1,"options":{"words":4,"addNumber":true}}' | \
          jq -r '.data.passwords[0]')
        
        # Store in team password manager
        op item create \
            --category=login \
            --title="$SERVICE-$MEMBER" \
            --field="username=$MEMBER" \
            --field="password=$PASSWORD" \
            --vault="Team Vault"
        
        echo "  $SERVICE: $PASSWORD"
    done
    echo ""
done

Security Considerations

API Security

1. Local Deployment: Run the API locally or on a secure internal network
2. Rate Limiting: The API includes built-in rate limiting (60 requests/minute by default)
3. No Logging of Passwords: Passwords are not logged in server logs
4. HTTPS: Use HTTPS in production deployments

Integration Security

1. Environment Variables: Store API endpoints in environment variables:

export PASSWORD_API_URL="https://passwords.internal.company.com/api/v1"

2. Script Permissions: Set appropriate permissions on scripts:

chmod 700 password-scripts/
chmod 600 password-scripts/*.sh

3. Secure Storage: Ensure integration scripts don't leave passwords in temporary files:

# Good: Use pipes and variables
PASSWORD=$(curl -s ... | jq -r '.data.passwords[0]')

# Bad: Don't write to temporary files
# curl -s ... > /tmp/password.json

Production Deployment

For production use, consider:

1. Authentication: Add API key authentication
2. Network Security: Deploy behind a firewall or VPN
3. Monitoring: Monitor API usage and failed requests
4. Backup: Regular backups of configuration and logs

Password Manager Sync

When integrating with password managers:

1. Verify Storage: Always verify passwords are correctly stored
2. Error Handling: Implement proper error handling for API failures
3. Rollback: Have procedures to rollback failed password updates
4. Audit Trail: Maintain logs of password generation and updates

Troubleshooting

Common Issues

API Connection Issues:

# Test API connectivity
curl -s http://localhost:8080/api/v1/health

# Check if service is running
netstat -tlnp | grep 8080

JSON Parsing Issues:

# Validate JSON response
curl -s http://localhost:8080/api/v1/passwords | jq '.'

# Check for errors
curl -s http://localhost:8080/api/v1/passwords | jq '.error'

Password Manager Integration:

# Test CLI tools separately
bw --version
op --version
keepassxc-cli --version

# Verify authentication
bw status
op whoami

This integration guide provides comprehensive examples for connecting the Password Generator API with popular tools and services. Adapt these examples based on your specific requirements and security policies.