> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyleeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Managing sensitive data securely in Pylee configurations

# Secrets

Secrets management in Pylee provides a secure way to handle sensitive information like API keys, passwords, tokens, and other confidential data. Rather than hardcoding these values in configuration files, Pylee offers multiple secure storage and retrieval mechanisms.

## What are Secrets?

Secrets are sensitive pieces of information that should never be stored in plain text or committed to version control. In Pylee, secrets include:

* **API keys and tokens**: Authentication credentials for external services
* **Database passwords**: Connection credentials for databases
* **Certificates and keys**: SSL/TLS certificates and private keys
* **Authentication tokens**: OAuth tokens and session keys
* **Encryption keys**: Keys used for data encryption and decryption

## Secret Storage Options

### Environment Variables

The simplest approach for storing secrets in environment variables:

```json theme={null}
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
```

### Secret References

Use special syntax to reference secrets stored in secure vaults:

```json theme={null}
{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["-m", "db_server"],
      "env": {
        "DATABASE_PASSWORD": "${secret:db_password}",
        "API_KEY": "${secret:external_api_key}"
      }
    }
  }
}
```

### File-based Secrets

Store secrets in secure files with restricted permissions:

```json theme={null}
{
  "mcpServers": {
    "api-server": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "API_KEY": "${file:/opt/secrets/api_key}",
        "JWT_SECRET": "${file:~/.pylee/secrets/jwt_secret}"
      }
    }
  }
}
```

## Secret Providers

### Local Secret Store

Pylee's built-in encrypted secret storage:

```bash theme={null}
# Store a secret
pylee secret set api_key "your-secret-key"

# List stored secrets
pylee secret list

# Remove a secret
pylee secret remove api_key
```

Configuration usage:

```json theme={null}
{
  "mcpServers": {
    "api-client": {
      "env": {
        "API_KEY": "${secret:api_key}"
      }
    }
  }
}
```

### External Secret Managers

#### AWS Secrets Manager

```json theme={null}
{
  "secretProviders": {
    "aws": {
      "type": "aws-secrets-manager",
      "region": "us-east-1"
    }
  },
  "mcpServers": {
    "app": {
      "env": {
        "DATABASE_URL": "${aws:prod/database/connection-string}"
      }
    }
  }
}
```

#### HashiCorp Vault

```json theme={null}
{
  "secretProviders": {
    "vault": {
      "type": "hashicorp-vault",
      "address": "https://vault.company.com",
      "auth": {
        "method": "token",
        "token": "${VAULT_TOKEN}"
      }
    }
  },
  "mcpServers": {
    "app": {
      "env": {
        "API_KEY": "${vault:secret/data/api-keys#key}"
      }
    }
  }
}
```

#### Azure Key Vault

```json theme={null}
{
  "secretProviders": {
    "azure": {
      "type": "azure-keyvault",
      "vaultUrl": "https://myvault.vault.azure.net/"
    }
  },
  "mcpServers": {
    "app": {
      "env": {
        "CONNECTION_STRING": "${azure:database-connection-string}"
      }
    }
  }
}
```

## Secret Syntax

### Basic Secret Reference

```json theme={null}
{
  "env": {
    "API_KEY": "${secret:api_key}"
  }
}
```

### Provider-specific References

```json theme={null}
{
  "env": {
    "AWS_SECRET": "${aws:prod/api-keys/external-service}",
    "VAULT_SECRET": "${vault:secret/data/config#password}",
    "AZURE_SECRET": "${azure:connection-string}"
  }
}
```

### Secret with Default Values

```json theme={null}
{
  "env": {
    "API_TIMEOUT": "${secret:api_timeout:-30}"
  }
}
```

### Complex Secret Structures

For JSON secrets:

```json theme={null}
{
  "env": {
    "DATABASE_CONFIG": "${secret:db_config}",
    "DB_HOST": "${secret:db_config#host}",
    "DB_PORT": "${secret:db_config#port}"
  }
}
```

## Security Best Practices

### Access Control

* Implement least-privilege access to secrets
* Use role-based access control (RBAC)
* Regularly audit secret access logs
* Rotate secrets regularly

### Storage Security

* Never commit secrets to version control
* Use encrypted storage for secret files
* Set restrictive file permissions (600 or 400)
* Store secrets separate from configuration

### Network Security

* Use HTTPS/TLS for secret transmission
* Implement proper certificate validation
* Use VPNs or private networks when possible
* Monitor secret access patterns

### Rotation and Lifecycle

* Implement automatic secret rotation
* Set expiration dates for secrets
* Have rollback procedures for secret changes
* Monitor for secret usage anomalies

## Environment-Specific Secrets

### Development Environment

```json theme={null}
{
  "environments": {
    "development": {
      "secretProviders": {
        "local": {
          "type": "local-store",
          "path": "~/.pylee/dev-secrets"
        }
      }
    }
  },
  "mcpServers": {
    "api": {
      "env": {
        "API_KEY": "${local:dev_api_key}",
        "DATABASE_URL": "postgresql://localhost:5432/dev"
      }
    }
  }
}
```

### Production Environment

```json theme={null}
{
  "environments": {
    "production": {
      "secretProviders": {
        "vault": {
          "type": "hashicorp-vault",
          "address": "${VAULT_ADDR}",
          "auth": {
            "method": "kubernetes"
          }
        }
      }
    }
  },
  "mcpServers": {
    "api": {
      "env": {
        "API_KEY": "${vault:secret/prod/api-keys#external-service}",
        "DATABASE_URL": "${vault:secret/prod/database#connection-string}"
      }
    }
  }
}
```

## Secret Templates

### Database Connection Template

```json theme={null}
{
  "templates": {
    "database_connection": {
      "env": {
        "DB_HOST": "${secret:${service}_db_host}",
        "DB_PORT": "${secret:${service}_db_port}",
        "DB_USER": "${secret:${service}_db_user}",
        "DB_PASS": "${secret:${service}_db_password}",
        "DB_NAME": "${secret:${service}_db_name}"
      }
    }
  },
  "mcpServers": {
    "user-service": {
      "template": "database_connection",
      "variables": {
        "service": "user"
      }
    }
  }
}
```

### API Client Template

```json theme={null}
{
  "templates": {
    "api_client": {
      "env": {
        "API_BASE_URL": "${secret:${service}_api_url}",
        "API_KEY": "${secret:${service}_api_key}",
        "API_TIMEOUT": "${secret:${service}_api_timeout:-30}"
      }
    }
  }
}
```

## Secret Validation

### Required Secrets

```json theme={null}
{
  "secrets": {
    "api_key": {
      "required": true,
      "description": "API key for external service",
      "type": "string",
      "pattern": "^sk-[a-zA-Z0-9]{32}$"
    },
    "database_password": {
      "required": true,
      "description": "Database connection password",
      "minLength": 12
    }
  }
}
```

### Secret Encryption

```json theme={null}
{
  "secretStore": {
    "encryption": {
      "algorithm": "AES-256-GCM",
      "keyDerivation": "PBKDF2",
      "iterations": 100000
    }
  }
}
```

## Advanced Features

### Secret Injection at Runtime

```json theme={null}
{
  "mcpServers": {
    "dynamic-service": {
      "command": "python",
      "args": ["-m", "service"],
      "secretInjection": {
        "method": "file",
        "path": "/tmp/secrets",
        "format": "json",
        "secrets": [
          "api_key",
          "database_password"
        ]
      }
    }
  }
}
```

### Secret Monitoring

```json theme={null}
{
  "secretMonitoring": {
    "enabled": true,
    "logAccess": true,
    "alertOnFailure": true,
    "rotationWarnings": {
      "enabled": true,
      "daysBefore": 7
    }
  }
}
```

### Multi-Region Secrets

```json theme={null}
{
  "secretProviders": {
    "primary": {
      "type": "aws-secrets-manager",
      "region": "us-east-1"
    },
    "fallback": {
      "type": "aws-secrets-manager",
      "region": "us-west-2"
    }
  },
  "mcpServers": {
    "api": {
      "env": {
        "API_KEY": "${primary:api-key||fallback:api-key}"
      }
    }
  }
}
```

## Troubleshooting

### Common Issues

#### Secret Not Found

```
Error: Secret 'api_key' not found in provider 'local'
```

**Solutions**:

* Verify secret exists: `pylee secret list`
* Check provider configuration
* Ensure proper access permissions

#### Permission Denied

```
Error: Access denied to secret 'database_password'
```

**Solutions**:

* Check IAM/RBAC permissions
* Verify authentication credentials
* Review secret access policies

#### Secret Decryption Failed

```
Error: Failed to decrypt secret 'encrypted_token'
```

**Solutions**:

* Verify encryption key is correct
* Check secret store integrity
* Ensure proper key permissions

### Debugging Secrets

Enable secret debugging (be careful in production):

```json theme={null}
{
  "debug": {
    "secrets": {
      "enabled": true,
      "maskValues": true,
      "logAccess": true
    }
  }
}
```

## Integration Examples

### Complete API Service Configuration

```json theme={null}
{
  "secretProviders": {
    "vault": {
      "type": "hashicorp-vault",
      "address": "${VAULT_ADDR}"
    }
  },
  "mcpServers": {
    "payment-service": {
      "command": "python",
      "args": ["-m", "payment_service"],
      "env": {
        "STRIPE_SECRET_KEY": "${vault:secret/payment/stripe#secret_key}",
        "STRIPE_WEBHOOK_SECRET": "${vault:secret/payment/stripe#webhook_secret}",
        "DATABASE_URL": "${vault:secret/payment/database#connection_string}",
        "JWT_SECRET": "${vault:secret/payment/auth#jwt_secret}",
        "ENCRYPTION_KEY": "${vault:secret/payment/encryption#master_key}"
      }
    }
  }
}
```

### Multi-Environment Secret Management

```json theme={null}
{
  "environments": {
    "development": {
      "secretProviders": {
        "local": {
          "type": "local-store"
        }
      }
    },
    "staging": {
      "secretProviders": {
        "aws": {
          "type": "aws-secrets-manager",
          "region": "us-east-1",
          "prefix": "staging/"
        }
      }
    },
    "production": {
      "secretProviders": {
        "aws": {
          "type": "aws-secrets-manager",
          "region": "us-east-1",
          "prefix": "prod/"
        }
      }
    }
  }
}
```

## Next Steps

* Learn about [Variables](/understanding-pylee/variables) for non-sensitive configuration
* Explore [Server configuration](/understanding-pylee/servers) for complete setup examples
* Check the [Troubleshooting](/support/troubleshooting) guide for secret-related issues
* Review security best practices for your deployment environment