API Keys

Overview

API keys allow you to access CalyxCRM programmatically through the REST API. Each API key is scoped to a single organization and can be used to automate tasks, integrate with external systems, or build custom applications.

Managing API Keys

Accessing the Developers Tab

1. Click on your organization name in the sidebar
2. Select Settings
3. Navigate to the Developers tab

Creating an API Key

1. In the Developers tab, click Create API Key
2. Enter a descriptive name for the key (e.g., "Production Integration", "CI/CD Pipeline")
3. Choose access permissions - Full access or select individual scopes
4. Optionally set an expiration date
5. Click Create
6. Important: Copy the API key immediately. For security reasons, the full key is only shown once and cannot be retrieved later.

API Key Format

API keys follow this format:

caly_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Prefix: caly_ (identifies CalyxCRM keys)
• Key body: 43 characters of random base64url-encoded data

Only the first 9 characters (e.g., caly_XXXX) are stored and displayed in the UI for identification purposes.

Viewing API Keys

The Developers tab shows a table of all API keys with:

Deleting an API Key

1. Find the key in the API Keys table
2. Click the delete icon in the Actions column
3. Type the exact name of the API key to confirm deletion
4. Click Delete

Deleted keys are immediately invalidated and cannot be recovered.

Security Best Practices

Key Storage

• Never commit API keys to version control
• Use environment variables or secure secret management systems
• Rotate keys periodically, especially for production systems

Key Permissions

• Use scoped keys to grant only the access each integration needs (e.g., records:read for a read-only dashboard)
• Create separate keys for different environments (development, staging, production)
• Create separate keys for different integrations
• Delete keys that are no longer needed

See the API Reference for the full list of available scopes.

Expiration

• Set expiration dates for temporary or contractor access
• Review and rotate long-lived keys periodically
• Monitor the "Last Used" column to identify unused keys

If a Key is Compromised

1. Immediately delete the compromised key
2. Create a new key
3. Update all systems using the old key
4. Review API logs for unauthorized access

Using API Keys

Authentication Header

Include your API key in the Authorization header of every request:

Authorization: Bearer caly_your_api_key_here

Example Request

curl -X GET "https://your-domain.com/api/v1/objects" \
  -H "Authorization: Bearer caly_your_api_key_here"

Error Responses

Rate Limits

API keys are subject to rate limiting to ensure fair usage:

• 100 requests per minute per API key

When rate limited, the API returns a 429 Too Many Requests status with headers indicating when you can retry:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067200
Retry-After: 45

Next Steps

Once you have an API key, see the API Reference for the complete list of available endpoints.