API Key Management

This document provides best practices for managing API keys with noidea.

Secure Storage

As of version v0.3.0, noidea securely stores API keys using your system's native keyring/keychain when available:

macOS: Uses the Keychain
Windows: Uses the Windows Credential Manager
Linux: Uses the Secret Service API (requires libsecret)

If the system keyring is unavailable, a fallback encrypted storage is used in ~/.noidea/secure/.

Setting Up Your API Key

You can set up your API key in several ways:

1. Using the CLI (Recommended)

# Set up API key securely
noidea config apikey

# Check API key storage status
noidea config apikey-status

# Remove a stored API key
noidea config apikey-remove

# Generate commands to clean environment variables
noidea config clean-env

When setting up a key with noidea config apikey, the system will: 1. Prompt for the API key (input is hidden for security) 2. Validate the key with the provider to ensure it works 3. Store the key securely in your system's keyring or fallback storage

The apikey-status command will: 1. Show which storage system is being used 2. Check if your API key is valid with a test request 3. Display whether the key is working correctly

2. Using Environment Variables (Alternative)

You can still use environment variables if you prefer:

# For xAI
export XAI_API_KEY=your_api_key_here

# For OpenAI
export OPENAI_API_KEY=your_api_key_here

# For DeepSeek
export DEEPSEEK_API_KEY=your_api_key_here

# Generic (will use whatever provider is configured)
export NOIDEA_API_KEY=your_api_key_here

Important Note: Environment variables will take precedence over secure storage. If you want to use secure storage, make sure these environment variables are not set.

3. Using .env Files (Not Recommended)

While still supported for backward compatibility, we recommend transitioning away from .env files:

# Create or edit ~/.noidea/.env
XAI_API_KEY=your_api_key_here

Provider Aliases

NoIdea supports a flexible provider aliasing system that maps different names to standard provider identifiers. This is helpful for users who might refer to the same provider by different names.

Built-in Aliases

The system comes with default aliases for common providers:

Standard Name	Recognized Aliases
`openai`	`open-ai`, `gpt`, `chatgpt`, `davinci`
`xai`	`x-ai`, `grok`, `x.ai`
`deepseek`	`deep-seek`, `deepseek-ai`
`anthropic`	`claude`, `anthropic-ai`
`mistral`	`mistral-ai`, `mistralai`

Custom Provider Aliases

You can define your own aliases by creating or editing the file ~/.noidea/secure/provider_aliases.json:

{
  "openai": ["openai-custom", "my-gpt"],
  "custom-provider": ["custom1", "custom2"]
}

When you first use the secure storage system, a template file is automatically created with examples.

Custom aliases are merged with the built-in ones, with your custom aliases taking precedence in case of conflicts.

For example, with the configuration above: - openai-custom would be normalized to openai - custom1 would be normalized to custom-provider - You can add entirely new providers not included in the built-in list

This feature is especially useful for: - Teams with custom naming conventions - Using providers not officially supported yet - Creating shortcuts for commonly used providers

API Key Priority Order

The system uses the following order of precedence when looking for API keys:

Environment variables (highest priority)
Secure storage (keyring/keychain or fallback encrypted file)
Config file (lowest priority - not recommended for API keys)

If you've set up a key using secure storage but it's not being used, check if any environment variables are overriding it with:

noidea config apikey-status

To clean environment variables and use secure storage instead:

noidea config clean-env

This will generate commands you can run to remove API key environment variables.

API Key Security Best Practices

Never commit API keys to version control
Ensure .env files are in your .gitignore
Use secure storage or environment variables instead
Rotate keys periodically
Change your API keys regularly
Use noidea config apikey to update your stored key
Use the least privileged key possible
Only use keys with the permissions your application needs
Monitor key usage
Check the provider's dashboard for unusual activity
Set up usage alerts if available
Environment separation
Use different keys for development and production

Troubleshooting

If you encounter issues with secure storage:

Check storage status and key validity
```
noidea config apikey-status
```
This command will verify:
If your keyring is available
If your API key is properly stored
If your API key is valid and working
Ensure dependencies are installed
On Linux, install libsecret: sudo apt-get install libsecret-1-dev
Remove environment variables
If secure storage is working but not being used, environment variables may be taking precedence
```
noidea config clean-env
```
If validation fails
Check if your API key is correct
Ensure you have an active subscription with the provider
Check if your network can reach the provider's API servers
Provider alias issues
If your provider isn't being recognized correctly, check or customize the aliases in ~/.noidea/secure/provider_aliases.json
Ensure the JSON file is valid and properly formatted

Migration from Previous Versions

If you're upgrading from a version before v0.3.0:

Use the migration script to move your API key to secure storage:
```
./scripts/migrate_to_secure.sh
```
Or run noidea config apikey to set up your API key securely
Remove any API keys from .env files or your config file
Remove API key environment variables with:
```
noidea config clean-env
```

For more information, please see the Configuration Guide.