API Key Management

n8n-deploy provides streamlined API key management for authenticating with n8n servers across multiple environments.

🎯 Overview

API keys in n8n-deploy serve as authentication tokens for n8n server operations:

Push/Pull Workflows: Sync workflows with remote servers
Server Management: Link keys to specific server instances
Multi-Environment Support: Manage separate keys for dev/staging/prod
Plain Text Storage: Simplified storage in SQLite (secure your database file!)

API keys are n8n JWT tokens generated from the n8n web interface under Settings → API.

🔑 API Key Operations

Add API Key

Store an API key with a memorable name:

# Interactive input (recommended for security) echo "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." | n8n-deploy apikey add - --name production_key  # Direct input (visible in shell history) n8n-deploy apikey add "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." --name staging_key  # Link to server during creation n8n-deploy apikey add - --name prod_key --server "Production Server 🚀"  # Add with description n8n-deploy apikey add - --name dev_key --description "Development environment key"  # Auto-link to server from environment N8N_SERVER_URL=http://n8n.local:5678 n8n-deploy apikey add - --name local_key 

Options:

--name: Unique identifier (supports UTF-8, emojis)
--server: Link to specific server (creates server if doesn’t exist)
--description: Optional documentation string

Pro Tip: Use descriptive names like prod_readonly or staging_admin to indicate environment and permission level.

List API Keys

View all stored API keys:

# Rich emoji output (credentials masked) n8n-deploy apikey list  # Script-friendly output (credentials masked) n8n-deploy apikey list --no-emoji  # Display actual credentials (SECURITY WARNING: use with extreme caution) n8n-deploy apikey list --unmask  # JSON format for parsing n8n-deploy apikey list --json 

Output includes:

Key name and description
Creation timestamp
Last used timestamp
Active/inactive status
Linked servers (if any)
API key credentials (only with --unmask flag)

Example output (credentials masked by default):

🔑 API Keys  ┌────────────────────┬─────────────────────┬──────────────┬────────────┐ │ Name               │ Created             │ Last Used    │ Status     │ ├────────────────────┼─────────────────────┼──────────────┼────────────┤ │ production_key     │ 2025-09-15 10:30:00 │ 2025-10-05   │ ✅ Active  │ │ staging_key        │ 2025-09-20 14:15:00 │ 2025-10-01   │ ✅ Active  │ │ dev_key            │ 2025-10-01 08:00:00 │ Never        │ ✅ Active  │ │ old_key            │ 2025-08-01 12:00:00 │ 2025-08-15   │ 🚫 Inactive│ └────────────────────┴─────────────────────┴──────────────┴────────────┘ 

Security Warning: The --unmask flag displays actual API credentials. Use only when absolutely necessary and never in logs, shared terminals, or automated scripts.

Test API Key

Validate an API key against an n8n server:

# Test key validity n8n-deploy apikey test production_key  # Test with specific server n8n-deploy --server-url http://n8n.example.com:5678 apikey test staging_key 

What testing checks:

Key format (JWT structure)
Server connectivity
Authentication success
Token expiration status

Example output:

🧪 Testing API key: production_key  ✓ Key format valid ✓ Server reachable (http://n8n.example.com:5678) ✓ Authentication successful ✓ Token expires: 2025-12-31  ✅ API key is valid and working 

Deactivate API Key

Soft-delete a key (keeps in database but marks inactive):

# Deactivate key n8n-deploy apikey deactivate old_key  # Confirm deactivation n8n-deploy apikey list | grep old_key 

Deactivated keys remain in database for audit purposes but cannot be used for operations.

Delete API Key

Permanently remove an API key:

# Delete with confirmation prompt n8n-deploy apikey delete old_key  # Force delete without confirmation n8n-deploy apikey delete temp_key --confirm  # Delete and unlink from all servers n8n-deploy apikey delete staging_key --confirm 

Permanent Action: Deleted keys cannot be recovered. Ensure you have backups or can regenerate from n8n.

🔗 Server-Key Association

Linking Keys to Servers

API keys can be associated with specific servers for automatic authentication:

# Link existing key to server n8n-deploy server link production_key "Production Server"  # Add key and link in one command n8n-deploy apikey add - --name prod_key --server "Production Server"  # View keys linked to server n8n-deploy server keys "Production Server" 

Benefits of linking:

Automatic authentication: No need to specify key for each operation
Multi-server support: Different keys for different environments
Organized management: Group keys by server purpose

Multi-Environment Workflow

Typical setup for DevOps teams:

# Development Environment n8n-deploy server create http://n8n-dev.internal:5678 --name "Development" n8n-deploy apikey add - --name dev_key --server "Development"  # Staging Environment n8n-deploy server create http://n8n-staging.internal:5678 --name "Staging" n8n-deploy apikey add - --name staging_key --server "Staging"  # Production Environment n8n-deploy server create https://n8n.example.com --name "Production 🚀" n8n-deploy apikey add - --name prod_key --server "Production 🚀"  # List all configurations n8n-deploy server list n8n-deploy apikey list 

🛡️ Security Best Practices

Storage Security

API keys are stored in plain text within the SQLite database. Protect your database:

# Set restrictive permissions chmod 600 ~/.n8n-deploy/n8n-deploy.db chmod 700 ~/.n8n-deploy  # For multi-user systems chown $USER:$USER ~/.n8n-deploy 

Key Generation

Generate secure API keys from n8n:

Open n8n web interface
Navigate to Settings → API
Click Create API Key
Copy the JWT token immediately
Store in n8n-deploy within 60 seconds

Best Practice: Generate separate keys for each environment and purpose (read-only vs. full access).

Key Rotation Strategy

Regular key rotation enhances security:

#!/bin/bash # rotate-keys.sh - Monthly key rotation script  # Generate new key in n8n first, then:  # Add new key echo "new_jwt_token" | n8n-deploy apikey add - --name prod_key_new --server "Production"  # Test new key n8n-deploy apikey test prod_key_new  # Deactivate old key n8n-deploy apikey deactivate prod_key_old  # After verification period, delete old key # n8n-deploy apikey delete prod_key_old --confirm 

📋 API Key Database Schema

CREATE TABLE api_keys (     id INTEGER PRIMARY KEY AUTOINCREMENT,     name TEXT NOT NULL UNIQUE,        -- Key identifier (UTF-8 supported)     api_key TEXT NOT NULL,            -- Plain text n8n JWT token     description TEXT,                 -- Optional documentation     created_at TIMESTAMP NOT NULL,    -- Creation time     last_used_at TIMESTAMP,           -- Last usage time     is_active INTEGER DEFAULT 1       -- Active status (1=yes, 0=no) );  CREATE TABLE server_api_keys (     server_id INTEGER NOT NULL,     api_key_id INTEGER NOT NULL,     created_at TIMESTAMP NOT NULL,     PRIMARY KEY (server_id, api_key_id),     FOREIGN KEY (server_id) REFERENCES servers(id) ON DELETE CASCADE,     FOREIGN KEY (api_key_id) REFERENCES api_keys(id) ON DELETE CASCADE ); 

The server_api_keys junction table enables many-to-many relationships between servers and API keys.

🆘 Troubleshooting

Invalid API Key Format

Error: Invalid JWT token format

Causes:

Incomplete token (copying error)
Extra whitespace or newlines
Expired token

Solutions:

# Verify token format (should start with eyJ) echo "$API_KEY" | head -c 10  # Remove whitespace API_KEY=$(echo "$API_KEY" | tr -d '[:space:]') echo "$API_KEY" | n8n-deploy apikey add - --name fixed_key 

Authentication Failed

Error: 403 Forbidden or 401 Unauthorized

Diagnosis:

# Test key explicitly n8n-deploy apikey test suspicious_key  # Check server connectivity curl -I http://n8n.example.com:5678  # Verify key in n8n interface # Settings → API → Active Keys 

Solutions:

Regenerate key in n8n
Check server URL is correct
Verify key hasn’t expired
Ensure key has necessary permissions

Server Management - Manage n8n server connections
Database Management - Database operations and backups
Configuration - Environment variables and settings
Workflow Management - Push/pull workflows using API keys
Troubleshooting - Common issues and solutions

💡 Pro Tips

Descriptive Naming: Use {environment}_{purpose} pattern (e.g., prod_readonly, staging_admin)
Regular Rotation: Rotate production keys every 90 days minimum
Separate Keys: Never share keys between environments
Test Before Deploy: Always test new keys before deactivating old ones
Audit Trail: Review last_used_at timestamps regularly
Backup Database: API keys are only stored in the database
Emergency Plan: Document key revocation procedures
Limit Permissions: Use n8n’s role-based permissions for granular access
Monitor Usage: Track key usage patterns for anomaly detection
CI/CD Ephemeral Keys: Use temporary keys that auto-delete after pipeline completion

Last Updated: October 2025 Security Notice: Always secure your n8n-deploy database with appropriate filesystem permissions

API Key Management

🎯 Overview

🔑 API Key Operations

Add API Key

List API Keys

Test API Key

Deactivate API Key

Delete API Key

🔗 Server-Key Association

Linking Keys to Servers

Multi-Environment Workflow

🛡️ Security Best Practices

Storage Security

Key Generation

Key Rotation Strategy

📋 API Key Database Schema

🆘 Troubleshooting

Invalid API Key Format

Authentication Failed

📖 Related Documentation

💡 Pro Tips