Skip to content

API Keys and Secrets Architecture

This document details the architecture, storage mechanisms, and security lifecycle for API keys and secrets across all deployment targets of WorkWingman.

Key Layers Summary

WorkWingman manages credentials across four distinct layers:

  1. User BYOK (Desktop Client): User-provided API keys stored locally in client secure storage.
  2. Cloud Runtime (GCP Secret Manager): Server-side secrets managed dynamically in cloud deployments.
  3. Declared Environment Ladder: System and process environment variables powering fallback configurations.
  4. Developer Fleet Secrets (~/.fleet-secrets/*.json): Machine-local JSON secret stores for local development environments (e.g., local Vikunja API tokens), strictly excluded from source control.

Desktop BYOK Policy

  • Bring Your Own Key: The desktop application operates on a strict BYOK model. The app NEVER automatically creates vendor accounts or provisions API keys for users.
  • Config-Gated Integrations: Free data sources are enabled by default. Paid third-party features remain disabled and hidden in the UI until valid keys are supplied by the user.
  • Client-Side Isolation: Desktop keys reside in local OS secure credential storage and are transmitted directly to the respective vendor APIs or authorized proxies.

Cloud Edition & GCP Secret Manager

  • Secret Manager Storage: Cloud runtime credentials are managed centrally in Google Cloud Platform (GCP) Secret Manager.
  • Gotcha (Version Disabling): Disabling a secret version in GCP Secret Manager does NOT automatically fall back to :latest. The active version must be republished explicitly before traffic will resolve correctly.

Vendor Integrations & Authentication

  • Anthropic API: Powers core LLM capabilities via llm-harness. Usage and metering for cloud instances are detailed in technical/cloud-finance-usage.md.
  • Google OAuth Client (Docs Reader): Google OAuth 2.0 PKCE flow facilitates docs-reader sign-in.
  • TODO(verify): Confirm exact storage path and config file location for Google OAuth client IDs and PKCE token caches.

Cross-References

For deeper technical implementations, refer to the following documents: - technical/integration-keys.md — Provider integration patterns. - technical/connections-and-sso.md — Enterprise SSO and connection workflows. - technical/byok-efficiency.md — Token optimization and local caching strategies.