Custom Trades CRM
Custom Trades CRMAPI docs

Authentication

All requests to the Developer API must be authenticated using an API key. API keys are scoped to your company and provide access to your company's data.

API Key Format

API keys follow this format:

ctc_live_<secret>

The secret is a base64url-encoded 32-byte random value. Example:

ctc_live_aBc123XyZ456...

Authentication Methods

You can authenticate requests using either of these methods:

curl https://customtradescrm.com/api/v1/companies/me \
  -H "Authorization: Bearer ctc_live_..."

Method 2: X-API-Key Header

curl https://customtradescrm.com/api/v1/companies/me \
  -H "X-API-Key: ctc_live_..."

Getting API Keys

API keys are managed in your Custom Trades CRM account:

  1. Navigate to Settings → Developer API section
  2. Click Create API key
  3. Enter a name for your key (e.g., "Production API", "Development")
  4. Copy the key immediately — it will only be shown once

Key Security

  • One-way storage: API keys are stored as SHA-256 hashes. The raw key cannot be retrieved after creation
  • Show once: The full key is displayed only once at creation. After that, only a masked prefix is shown
  • Key rotation: Rotate keys periodically (recommended every 90 days) or if compromised
  • Key limits: Maximum 5 API keys per company

IP Restrictions

You can optionally restrict API keys to specific IP addresses or CIDR ranges:

  • No restrictions: Key works from any IP address (default)
  • IP allowlist: Specify one or more IP addresses or CIDR ranges (e.g., 192.168.1.100 or 192.168.1.0/24)

IP restrictions are managed per key in Settings → Developer API → Manage IP restrictions.

Key Management

  • Create: Generate new API keys in Settings
  • List: View all your API keys (masked) with last used timestamps
  • Rotate: Generate a new secret for an existing key (old key is invalidated)
  • Disable: Temporarily disable a key without deleting it
  • Delete: Permanently revoke a key

Best Practices

  1. Use different keys for different environments (production, staging, development)
  2. Rotate keys regularly (every 90 days recommended)
  3. Use IP restrictions for production keys when possible
  4. Never commit API keys to version control
  5. Monitor key usage via the request logs in Settings

Error Responses

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "success": false,
  "error": "Invalid API key."
}

Common authentication errors:

  • "Missing or invalid API key." - No API key provided or invalid format
  • "Invalid API key." - Key not found or hash mismatch
  • "API key is disabled." - Key exists but is disabled
  • "Developer API add-on required." - Company doesn't have active Developer API subscription
  • "Request not allowed from this IP for this key." - IP restriction violation