Managing API Keys

API Key Overview

API keys authenticate external applications to access your Commish data through the REST API. Each key is scoped to your organization and can be configured with specific permissions.

Creating an API Key

• Go to Admin → Settings → API Keys
• Click "Create API Key"
• Enter a descriptive name (e.g., "Salesforce Integration", "Claude MCP Server")
• Select the scopes:

- read — View deals, comp plans, commissions, SPIFFs, and users

- write — Create and update deals (includes read)

- admin — Full access including approvals, plan management, and webhooks (includes read + write)

• Optionally set an expiration date
• Click Create and copy the key immediately — it won't be shown again

Key Format

All Commish API keys follow a predictable format:

• Live keys: cm_live_ followed by 64 hex characters
• Test keys: cm_test_ followed by 64 hex characters

Test keys work identically to live keys but are intended for development and testing environments.

Revoking a Key

• Go to Admin → Settings → API Keys
• Find the key you want to revoke
• Click Revoke — this takes effect immediately
• Any application using that key will receive a 401 Unauthorized error

Rate Limits

Each API key is limited to 100 requests per minute. If you exceed this limit, the API returns a 429 Too Many Requests response with a Retry-After header.

Best Practices

• Create separate keys for each integration (don't share one key across multiple services)
• Use the minimum scope needed for each integration
• Set expiration dates for temporary integrations or contractor access
• Rotate keys periodically — create a new key, update your integration, then revoke the old one
• Monitor usage in Admin → Settings → API Keys to spot unusual activity