1. Treat API Keys Like Passwords
-Your API keys grant access to your account and potentially sensitive operations. Handle them with the same level of security you would apply to your account password or other critical credentials.
-Understanding Key Types
-2. Use Unique Keys for Different Applications & Environments
-Generate distinct API keys for different applications, services, or integrations that need access. If a key for one application is compromised, you can revoke it without disrupting others. Use separate keys for development, staging, and production environments.
-Tip: Use the "Name" field when creating keys to easily identify their purpose (e.g., "Production Zapier Integration", "Staging iOS App").
-Secret Keys
+Secret keys provide full access to your account and should be treated like passwords.
+-
+
- Never expose in client-side code (browsers, mobile apps, desktop apps) +
- Never commit to version control (Git, etc.) +
- Store securely using environment variables or secrets management +
- Can be revoked immediately if compromised +
3. Never Expose Keys in Client-Side Code
-Never embed API keys directly in mobile apps (iOS, Android), browser-side JavaScript, desktop applications, or any code that resides on a user's device. Exposed keys can be easily extracted by malicious actors.
-Solution: Route API requests through your own backend server. Your server can securely store and use the API key to communicate with the target API on behalf of the client.
-Publishable Keys
+Publishable keys are designed for client-side use with limited, safe permissions.
+-
+
- Safe to embed in browser JavaScript, mobile apps, and public code +
- Limited access — cannot perform sensitive operations +
- Always visible — you can view the full key anytime in your dashboard +
- Cannot be revoked — designed to be long-lived identifiers +
4. Never Commit Keys to Version Control (e.g., Git)
-Committing keys to your source code repository (like Git, Mercurial, etc.) is a common and dangerous mistake. Even in private repositories, accidental pushes or repository breaches can leak your keys.
-Solution: Store keys in environment variables or use a dedicated secrets management system. Access the key in your code via these secure methods.
-Essential Practices
-5. Securely Store Keys on Your Backend
--
-
- Environment Variables: The simplest secure method for many applications. Set an environment variable (e.g., `YOUR_SERVICE_API_KEY`) on your server and access it in your code (e.g., `ENV['YOUR_SERVICE_API_KEY']` in Ruby/Rails). -
- Secrets Management Services: For more robust needs, especially in production or team environments, use dedicated services like HashiCorp Vault, AWS Secrets Manager, Google Secret Manager, Doppler, etc. These provide encrypted storage, access control, auditing, and often automated rotation capabilities. -
- Encrypted Configuration Files: If using configuration files, ensure they are encrypted (e.g., Rails encrypted credentials `config/credentials.yml.enc` and `Rails.application.credentials`). <%= link_to "More info here", "https://guides.rubyonrails.org/security.html#custom-credentials", target: "_blank", rel: "noopener noreferrer", class: "text-primary" %>. -
Treat Secret Keys Like Passwords
+Your API keys grant access to your account. Handle them with the same care you would apply to your account password.
+ +Use Separate Keys for Different Purposes
+Create distinct keys for different applications and environments. If one key is compromised, you can revoke it without disrupting others.
+Tip: Use descriptive names like "Production Backend" or "Staging iOS App" to easily identify each key's purpose.
+ + <% unless key_types_feature_enabled? %> +Never Expose Keys in Client-Side Code
+Never embed API keys in mobile apps, browser JavaScript, or desktop applications. Exposed keys can be easily extracted by malicious actors.
+Solution: Route API requests through your own backend server, which can securely store and use the API key.
+ <% end %>6. Implement the Principle of Least Privilege (Scopes)
-If the API service supports it (and this `api_keys` gem allows for scopes), create keys with only the minimum permissions (scopes) required for their specific task. Avoid using a key with full access if only read access is needed.
-Note: Scope availability and enforcement depend on how the host application integrates and utilizes the `scopes` attribute provided by this gem.
+Secure Storage
+ +Environment Variables
+The simplest secure method. Set an environment variable on your server:
+# In your shell or deployment config
+export YOUR_SERVICE_API_KEY="sk_..."
+
+# Access in Ruby
+ENV['YOUR_SERVICE_API_KEY']Rails Encrypted Credentials
+For Rails applications, use encrypted credentials:
+# Edit credentials
+bin/rails credentials:edit
+
+# Access in code
+Rails.application.credentials.your_service_api_key<%= link_to "Rails Security Guide", "https://guides.rubyonrails.org/security.html#custom-credentials", target: "_blank", rel: "noopener noreferrer", class: "text-primary" %>
+ +Secrets Management Services
+For production environments, consider dedicated services like HashiCorp Vault, AWS Secrets Manager, or Google Secret Manager.
7. Monitor Usage and Rotate Keys Regularly
--
-
- Monitor Usage: Regularly check API usage logs or dashboards (if provided by the service or your monitoring tools). Look for unexpected spikes in activity or requests from unusual locations, which could indicate a compromised key. -
- Rotate Keys: Periodically generate new keys and revoke old ones (key rotation). This limits the window of opportunity for attackers if a key is ever leaked undetected. How often you rotate depends on your security requirements (e.g., every 90 days, annually).
-
Tip: This dashboard allows creating multiple keys, facilitating rotation. Create a new key, update your application(s), verify they work, and then revoke the old key.
- - Revoke Immediately if Compromised: If you suspect a key has been leaked or compromised, revoke it immediately using the "Revoke" button on your keys dashboard. -
Monitoring & Rotation
+ +Monitor Usage
+Regularly check for unexpected activity spikes or requests from unusual locations, which could indicate a compromised key.
+ +Rotate Keys Periodically
+Generate new keys and revoke old ones on a regular schedule (e.g., every 90 days). This limits exposure if a key is leaked undetected.
+Tip: Create a new key first, update your application, verify it works, then revoke the old key.
+ +Revoke Immediately if Compromised
+If you suspect a key has been leaked, revoke it immediately from your dashboard.
8. Use HTTPS Exclusively
-Ensure all API requests are made over HTTPS to encrypt the connection and prevent eavesdropping. Transmitting keys over unencrypted HTTP is highly insecure.
+Always Use HTTPS
+Ensure all API requests are made over HTTPS. Transmitting keys over unencrypted HTTP exposes them to eavesdropping.
-
By following these best practices, you significantly reduce the risk associated with API key management.
- - <%# Link back to the keys index if appropriate %> - <% if defined?(api_keys.keys_path) %> -<%= link_to "Back to API Keys", api_keys.keys_path, class: "text-primary" %>
- <% end %> +<%= link_to "Back to API Keys", api_keys.keys_path, class: "text-primary" %>
-