SocialMapper now includes secure API key management to protect your credentials. This guide covers how to securely store and use API keys with SocialMapper.
# Install with security features
pip install socialmapper[security]
# Or install individual dependencies
pip install keyring cryptography# Store Census API key (recommended method)
python -m socialmapper.security.cli set census_api YOUR_API_KEY
# Verify key is stored
python -m socialmapper.security.cli get census_api
# List all stored keys
python -m socialmapper.security.cli listfrom socialmapper import SocialMapper
# Keys are automatically loaded from secure storage
mapper = SocialMapper() # No need to pass API key
# Or explicitly get a key
from socialmapper.security.utils import get_api_key
api_key = get_api_key("census_api")SocialMapper supports multiple secure storage backends, automatically selecting the most secure available option:
- Windows: Windows Credential Vault
- macOS: Keychain
- Linux: Secret Service API (GNOME Keyring, KWallet)
from socialmapper.security import SecureKeyManager, KeyStorage
manager = SecureKeyManager()
manager.set_key("census_api", "your_key", KeyStorage.KEYRING)Keys are encrypted using Fernet symmetric encryption and stored in ~/.socialmapper/keys.enc
manager.set_key("census_api", "your_key", KeyStorage.ENCRYPTED_FILE)For backward compatibility, environment variables are still supported as a fallback:
export CENSUS_API_KEY="your_api_key"If you have existing API keys in environment variables, migrate them to secure storage:
# Automatic migration
python -m socialmapper.security.cli migrate
# Manual migration
python -c "from socialmapper.security.utils import migrate_from_env; migrate_from_env()"from socialmapper.security import SecureKeyManager
# Create key manager
manager = SecureKeyManager()
# Store a key
manager.set_key("census_api", "your_api_key")
# Retrieve a key
api_key = manager.get_key("census_api")
# Delete a key
manager.delete_key("census_api")
# Validate key format
is_valid = manager.validate_key("census_api", "test_key")# Use temporary keys
with manager.temporary_key("census_api", "temporary_key"):
# Temporary key is active here
api_key = manager.get_key("census_api")
# Original key is restored
# List all keys
keys = manager.list_keys()
# {'keyring': ['census_api'], 'environment': ['MAPBOX_TOKEN']}
# Custom storage configuration
manager = SecureKeyManager(
app_name="my_app",
config_path="~/my_app/keys.enc",
storage_preference=[KeyStorage.ENCRYPTED_FILE, KeyStorage.ENVIRONMENT]
)# Store a key
python -m socialmapper.security.cli set census_api YOUR_KEY
# Store with specific backend
python -m socialmapper.security.cli set census_api YOUR_KEY --storage keyring
# Get a key (masked by default)
python -m socialmapper.security.cli get census_api
# Show full key value
python -m socialmapper.security.cli get census_api --show
# Delete a key
python -m socialmapper.security.cli delete census_api
# Delete from all backends
python -m socialmapper.security.cli delete census_api --all
# Validate a key
python -m socialmapper.security.cli validate census_api
# List all keys
python -m socialmapper.security.cli list
# Migrate from environment
python -m socialmapper.security.cli migrateAdd to .gitignore:
.env
*.key
*.enc
~/.socialmapper/
# Development
manager.set_key("census_api_dev", dev_key)
# Production
manager.set_key("census_api_prod", prod_key)# Store new key
manager.set_key("census_api", new_key)
# Validate new key works
if validate_api_key("census_api", new_key):
# Remove old key
manager.delete_key("census_api_old")Encrypted key files are automatically created with restricted permissions (600), but verify:
ls -la ~/.socialmapper/
# Should show: -rw------- for .master.key and keys.enc# Keys are only available within context
with manager.temporary_key("api_key", sensitive_value):
perform_api_call()
# Key is automatically cleaned upIf keyring is not available on your system:
# Linux: Install system keyring
sudo apt-get install gnome-keyring # Debian/Ubuntu
sudo yum install gnome-keyring # RHEL/CentOS
# Or use encrypted file storage instead
python -m socialmapper.security.cli set census_api YOUR_KEY --storage encrypted# Fix permissions on key files
chmod 600 ~/.socialmapper/.master.key
chmod 600 ~/.socialmapper/keys.encIf you lose the master key for encrypted storage:
# Remove encrypted files
rm -rf ~/.socialmapper/
# Re-initialize and re-add keys
python -m socialmapper.security.cli set census_api YOUR_KEYFor backward compatibility, the following environment variables are still checked as fallbacks:
CENSUS_API_KEY- US Census Bureau API keyMAPBOX_TOKEN- Mapbox access tokenGOOGLE_MAPS_API_KEY- Google Maps API key
However, we strongly recommend migrating to secure storage.
- Keyring Security: System keyrings are generally secure but depend on OS implementation
- Encrypted Files: Use Fernet (AES-128) encryption with PBKDF2 key derivation
- Master Key: Stored separately from encrypted data with restricted permissions
- Memory Safety: Keys are not logged or included in error messages
- Process Safety: Keys in environment variables can be visible in process listings
For security issues or questions:
- Open an issue: https://github.com/mihiarc/socialmapper/issues
- Security vulnerabilities: Contact maintainers directly
Remember: Never share your API keys publicly or commit them to version control!