Workjet
Back to Workjet

Credential Management

Workjet handles multiple types of credentials across its three security zones. Every credential type is stored and managed using security best practices appropriate for its sensitivity level and usage pattern.

Credential Types

Credential Zone Storage Protection
Workjet API key Gateway D1 database SHA-256 hash (raw key never stored)
Session cookie Gateway KV store HttpOnly, Secure, SameSite=Lax
MCP connector tokens Device OS Keychain Platform-native encryption
AI provider API keys Gateway D1 (encrypted) AES-256 at rest, owner-only access
Google OAuth tokens Gateway KV store Short-lived access tokens, secure refresh

API Key Lifecycle

  1. Creation: Admin generates key in Portal. Raw key shown once.
  2. Hashing: Key is SHA-256 hashed. Only the hash is stored.
  3. Distribution: User copies the raw key to the desktop app or script.
  4. Usage: Each request includes the key. Gateway hashes it and compares to stored hashes.
  5. Rotation: Create a new key, update applications, revoke the old key.
  6. Revocation: Hash is deleted from the database. Key is immediately invalid.

Key rotation: Rotate API keys periodically (every 90 days recommended). Create the new key before revoking the old one to avoid downtime.

MCP Connector Credentials

Credentials for MCP connectors (GitHub tokens, Slack bot tokens, database passwords, etc.) are stored exclusively on the user's device:

  • Entered during the Connection Wizard
  • Stored in the OS keychain immediately
  • Injected as environment variables when the MCP server process starts
  • Never transmitted to the Workjet gateway or any cloud service
  • Removed from the keychain when the connector is deleted

Session Management

  • Sessions expire after 7 days of inactivity
  • Active sessions are refreshed on each request
  • Sessions can be explicitly terminated (sign out)
  • Removing a user from the organization invalidates all their sessions

Best Practices

  • Use fine-grained API keys with minimal permissions for MCP connectors
  • Rotate Workjet API keys every 90 days
  • Use read-only database credentials for database connectors
  • Store API keys in a secrets manager if using them in CI/CD pipelines
  • Review active API keys periodically and revoke unused ones

Next Steps