Security

Best practices for securing your API keys and applications.

API Key Handling

API keys are the primary authentication mechanism for WhizAI. Here's what you need to know:

Key Format

API keys use a two-tier prefix that identifies the environment:

cw_dev_<random_string>— development keys
cw_prod_<random_string>— production keys

Use cw_dev_* keys in development and staging environments. Use cw_prod_* keys in production only.

Authentication Header

Pass your API key using either header format:

X-API-Key: cw_prod_...
Authorization: Bearer cw_prod_...

Key Generation & Storage

  • Keys are generated using cryptographically secure random generation
  • The full key is shown only once at creation — store it securely immediately
  • Key prefix (first 12 characters) is visible in the dashboard for identification
  • Keys are hashed with bcrypt before storage — plaintext is never persisted

Capability-Only Access

Regular API keys (cw_dev_* / cw_prod_*) are capabilities-only. Attempting to call workflow execution endpoints directly will return a 403 WORKFLOW_EXECUTION_FORBIDDEN error.

Access Matrix

Auth TypeCapability ExecutionWorkflow Execution
Regular API key (cw_dev_* / cw_prod_*)AllowedBlocked — 403
JWT session (dashboard)AllowedAllowed

This restriction ensures external integrations consume stable capability contracts rather than internal workflow slugs, protecting your app from internal platform changes.

App-Level Isolation

Each app is completely isolated:

  • API keys are scoped to a specific app
  • All data is isolated per app — no cross-app access is possible
  • Usage and ACU spend are tracked per app
  • Capabilities are scoped to the app's organization

This means you can safely use the same WhizAI account for multiple projects without data leakage between them.

Permission Scopes

API keys carry capability-scoped permissions. Scopes control which capabilities a key can invoke:

  • capabilities.execute — Run capability endpoints
  • capabilities.read — List and inspect available capabilities
  • artifacts.read — Read generated artifacts
  • runs.read — Read run status and history

Use the principle of least privilege — only grant the scopes your application needs.

Best Practices for Production

1. Store Keys Securely

  • Never commit API keys to version control
  • Use environment variables or secret management services (e.g., AWS SSM)
  • Rotate keys regularly and after team member offboarding
  • Use cw_dev_* keys in non-production environments, cw_prod_* in production

2. Use Appropriate Scopes

  • Create separate keys for different services and environments
  • Use read-only scopes where writes are not required
  • Revoke keys that are no longer in use immediately

3. Monitor Usage

  • Review ACU spend and API activity regularly in your dashboard
  • Investigate unexpected spikes in usage or failed authentication attempts
  • Revoke and replace any key you suspect has been compromised

4. Use HTTPS

Always use HTTPS when making API calls to https://api.whizur.ai. Never send API keys over unencrypted connections.

What WhizAI Does NOT Do

For transparency and trust, here's what WhizAI does NOT do:

  • We do NOT store API keys in plaintext — they are bcrypt-hashed at creation
  • We do NOT return full key values after initial creation
  • We do NOT share data between apps or organizations
  • We do NOT use your data to train models (unless explicitly agreed)
  • We do NOT log request/response bodies (only metadata)
  • We do NOT expose your data to other customers

Need Help?

If you suspect a key has been compromised, revoke it immediately in your dashboard and generate a new one.

API Reference