Skip to content
GhostMind

Security Guide

Developer Security Guide

API Key Storage

  • Store API keys in environment variables or a secret manager — never in source code
  • Use $GHOSTMIND_API_KEY in examples, not hardcoded values
  • Never commit API keys to Git repositories
  • Rotate keys periodically — revoke old keys when no longer needed
Terminal window
# Good — environment variable
export GHOSTMIND_API_KEY="gmk_live_..."
curl -H "Authorization: Bearer $GHOSTMIND_API_KEY" ...


# Bad — hardcoded key
curl -H "Authorization: Bearer gmk_live_actual_key_here" ...

Server-Side Usage

GhostMind API keys grant access to your workspace’s conversations, files, and connected accounts. Use GhostMind from your backend servers only.

Do not embed long-lived API keys in:

  • Public frontend code (React, Vue, etc.)
  • Mobile app binaries
  • Browser extensions
  • Any client-side code accessible to end users

If you need to expose GhostMind functionality to frontend clients, proxy requests through your own backend that injects the API key server-side.

Workspace Isolation

  • API keys are scoped to a single workspace
  • Conversations, files, and assets are tenant-isolated
  • An API key from workspace A cannot access workspace B’s resources
  • Cross-tenant access returns 403 or 404 (not 403 with details)

Artifact Authorization

  • Asset downloads require authentication with the workspace’s API key
  • Assets are scoped to the workspace that owns the conversation
  • Download URLs are not publicly accessible — they require the Authorization header
  • Expired or deleted assets return 404

Provider Credential Ownership

  • Provider credentials (ChatGPT sessions, Savio accounts) are stored securely in GhostMind — you do not pass them with each API call
  • Users connect their own provider accounts through the User App’s secure browser flow
  • GhostMind never exposes provider session tokens, cookies, or credentials via the API
  • Do not attempt to extract or share provider session material

Secret Rotation

  • Rotate API keys periodically (every 90 days recommended)
  • Revoke keys immediately if compromised
  • Reconnect provider accounts if sessions expire (the API returns ACCOUNT_REAUTH_REQUIRED)
  • Never share API keys between team members — create separate keys per user/service

What Never to Do

  • Never print API keys in logs, error messages, or chat output
  • Never share API keys in screenshots or documentation
  • Never store API keys in client-side localStorage or cookies
  • Never proxy user requests directly to GhostMind with your API key exposed
  • Never attempt to extract provider session tokens from GhostMind responses

Next Steps