Research alternative secure and user-friendly API key management approaches

[petertzy]

Description:

Currently, provider API keys are stored in the system keychain. This approach provides strong security, but it often requires entering the administrator password to maintain access, which affects usability.

We would like to explore alternative solutions that strike a better balance between security and convenience.

For example, in OpenClaw, API keys are stored in a JSON file on Linux systems. However, based on feedback from Chatty, this approach is considered insecure, so it has not been adopted.

Task:

• Research how established companies or widely-used tools manage API keys and secrets.

• Evaluate approaches in terms of:

  • Security
  • Ease of use
  • Cross-platform compatibility

• Consider alternatives such as:

  • Encrypted local storage
  • OS-native credential managers
  • Environment variables
  • Secret management services

Please document your findings in the comments of this issue.

If a suitable solution is identified, a follow-up implementation task will be created for contributors.

Thanks.

[sidharth-vijayan]

hey @petertzy,

Research on API Key Storage Approaches

1. OS-Native Credential Managers

Used by tools like GitHub CLI and VS Code.

Description:
Credentials are stored in OS-provided secure storage (e.g., macOS Keychain, Windows Credential Manager, Linux Secret Service).

Pros:

Strong security (OS-level encryption and access control)
Trusted and widely adopted
No need to implement custom encryption

Cons:

May prompt for administrator/system password
UX friction depending on OS configuration
Cross-platform differences in behavior

2. Plain Text Config Files (e.g., JSON)

Used in some simpler tools, but generally discouraged.

Description:
API keys are stored in local files (e.g., JSON or YAML).

Pros:

Very easy to implement and use
Fully cross-platform

Cons:

Insecure (plain text storage)
Risk of accidental exposure (e.g., committing to version control)
Not suitable for sensitive credentials

3. Encrypted Local Storage

Used by tools like 1Password and Bitwarden.

Description:
Secrets are stored in a local file but encrypted, typically using a master password or derived key.

Pros:

Better UX than OS keychain in some cases
Can be cross-platform
More secure than plain text storage

Cons:

Requires secure key management
If encryption key is stored locally, security is weakened
Adds implementation complexity

4. Environment Variables

Widely used in tools like Docker and AWS CLI.

Description:
API keys are provided via environment variables at runtime.

Pros:

Simple and flexible
No persistent storage required
Works well in development and CI/CD environments

Cons:

Not persistent across sessions unless manually configured
Can be exposed via logs or process inspection
Less user-friendly for non-technical users

5. Secret Management Services

Examples include HashiCorp Vault and AWS Secrets Manager.

Description:
Secrets are stored and accessed via external services.

Pros:

High level of security (rotation, auditing, access control)
Suitable for production and team environments

Cons:

Overkill for local desktop applications
Requires setup, network access, and possibly cost
Adds operational complexity

Recommendation

A hybrid approach appears to provide the best balance between security and usability:

Primary option: Continue using OS-native credential managers for secure storage.
Fallback option: Provide an encrypted local storage mechanism to reduce frequent password prompts and improve UX.

[petertzy]

Your proposed hybrid approach sounds very reasonable:

A hybrid approach appears to provide the best balance between security and usability:

Primary option: Continue using OS-native credential managers for secure storage.
Fallback option: Provide an encrypted local storage mechanism to reduce frequent password prompts and improve UX.

Based on this, I came up with the following two possible solutions:

---

1. Introduce a caching layer

On startup:

• Read credentials from the Keychain → store them in memory

During runtime:

• Use the in-memory values directly (no further Keychain access)

On shutdown:

• Clear the in-memory cache

Benefits:

• Avoids frequent password prompts
• Maintains strong security

---

2. Hybrid model

• Keychain → stores a master key
• Local storage → stores encrypted API keys

Flow:

First time setup:

• Generate a master key
• Store it in the Keychain

Storing API keys:

• Encrypt API keys using the master key
• Store them in a local JSON file (encrypted)

At runtime:

• Retrieve the master key from the Keychain (once)
• Decrypt the JSON file

---

Request

Could you come up with your own version of an implementation approach and outline the concrete steps for it? Thanks!

[gpalomino91]

Hi @petertzy, I’d like to help with this issue.

I’m still learning about this topic, but I found the discussion interesting and I’d like to understand it better. I can start by reading the current implementation and then try to share a simple idea or proposal if that would be useful.

[petertzy]

Hi @petertzy, I’d like to help with this issue.

I’m still learning about this topic, but I found the discussion interesting and I’d like to understand it better. I can start by reading the current implementation and then try to share a simple idea or proposal if that would be useful.

Thank you for your participation. The reason I want to address this issue is twofold. First, it genuinely causes inconvenience in use. Second, if this software is released in the future, it could confuse users, because they wouldn’t know how the code is implemented. Therefore, I want to resolve this problem in advance.
Recently, however, I received a new clue: the current storage method might not need to be changed. Once the software enters production, there may be a certification mechanism integrated with the system—such as a signature verification—where the system would automatically recognize the software as trustworthy, and the prompt would no longer appear. But this is not certain yet and requires testing.
That said, if there were a solution that could completely prevent the prompt from appearing in any situation while still addressing security concerns, that would be even better. In some respects, tools like Chatty are still far from the level of human experience and understanding. Therefore, I’m reaching out to gather valuable insights or expertise from anyone with experience in this area, for the benefit of everyone.

[gpalomino91]

Thanks for the explanation. That makes sense.

I’ll try to first understand where the current prompt is coming from and whether it is mainly a development/signing issue or something related to the current storage approach itself.

Then I can come back with a simple summary of what I find and a possible direction.

[sidharth-vijayan]

Request

Could you come up with your own version of an implementation approach and outline the concrete steps for it? Thanks!

hey so i think

1. Keep OS Credential Manager as Root of Trust
   Store a single master key in the OS-native credential manager (Keychain / Credential Vault / Secret Service)
   This avoids storing raw API keys there repeatedly and reduces frequent prompts
2. Encrypted Local Store for API Keys
   Store API keys in a local file (JSON or SQLite), but fully encrypted
   Use authenticated encryption (e.g., AES-GCM or ChaCha20-Poly1305)
   The file should include:
   ciphertext
   nonce/IV
   version metadata (for future upgrades)
3. Runtime Flow
   On First Setup
   Generate a strong random master key (256-bit)
   Store it in the OS credential manager
   Initialize an empty encrypted store
   On Startup
   Retrieve master key from OS credential manager (once)
   Decrypt the local encrypted store
   Load API keys into an in-memory cache

👉 After this, no further Keychain access is needed during runtime

During Runtime
Read API keys from memory (fast, no prompts)
On update:
Update in-memory cache
Re-encrypt data
Atomically write back to disk
On Shutdown
Clear in-memory cache (best effort depending on language/runtime)
4. Why This Works Well

Security:

OS credential manager remains the root of trust
No plaintext secrets on disk
Encrypted store protected with modern crypto

Ease of Use:

Eliminates repeated password prompts
Smooth runtime experience

Cross-Platform:

Works consistently across macOS, Windows, and Linux
Only relies on standard OS credential APIs + local file
5. Optional Enhancements (Future)
Key rotation support (re-encrypt store with new master key)
File integrity checks (detect tampering)
Session-based “lock/unlock” if needed

This approach keeps the strong security guarantees of OS-native storage, while improving usability by:
minimizing credential manager access
introducing a fast, encrypted local cache layer

[petertzy]

This is exactly the approach I would like to adopt, and you’ve even outlined a more advanced version for future development. I understand that implementing such a change would require a significant amount of development time. I’m not sure if you currently have the time and interest to work on this and create a PR, but I would really appreciate it. Thanks.