API Keys and Management¶
This document covers API key management for WhiteLabelCRO administrators.
What are API Keys¶
API keys authenticate external systems connecting to the WhiteLabelCRO Integration API. Each key: - Identifies your organization - Controls what operations are permitted (scopes) - Can be revoked immediately if compromised - Tracks last usage timestamp
Creating API Keys¶
Via Admin Portal¶
- Navigate to Settings > Integrations > API Keys
- Click Create New Key
- Enter a friendly name (e.g., "Zapier Integration", "HubSpot Sync")
- Select required scopes (see below)
- Click Create
- Copy the generated key immediately
Critical: The full API key is displayed only once. If you lose it, you must create a new key.
Via API¶
API key creation is performed through the Admin Portal. Programmatic key management is not currently available.
API Key Scopes¶
Scopes control what operations an API key can perform. Select only the scopes needed for each integration.
Available Scopes¶
| Scope | Permits | Use Case |
|---|---|---|
events:read |
Poll events via GET /api/v1/events | Zapier triggers, custom integrations |
webhooks:write |
Create/manage webhook subscriptions | Real-time push notifications |
integrations:read |
Search clients and affiliates | Deduplication, lookup workflows |
integrations:write |
Create/update records | Inbound lead capture, CRM sync |
admin |
Test event creation | Development and testing |
Scope Recommendations¶
Zapier or automation platforms:
- events:read - For triggers
- integrations:read - For searches
- integrations:write - For actions
Webhook-only integrations:
- webhooks:write - To manage subscriptions
- Optionally events:read - For fallback polling
Development/testing:
- admin - To generate test events
- Plus scopes for features being tested
Key Lifecycle¶
Active Keys¶
Active keys authenticate normally. The system tracks lastUsedUtc to help identify inactive keys.
Naming Keys¶
Use descriptive names to identify purpose later: - ✅ "Zapier Production Integration" - ✅ "HubSpot Lead Sync" - ❌ "Key 1" - ❌ "Test"
Rotation¶
To rotate a key: 1. Create a new key with the same scopes 2. Update the external system with the new key 3. Test the integration 4. Revoke the old key
There is no "regenerate" function. Rotation requires creating a new key.
Revocation¶
Revoke keys immediately if: - Key is compromised or exposed - Integration is no longer in use - Employee with key access leaves
Effects of revocation: - Immediate - all requests with the revoked key return 401 - Cannot be undone - Create a new key to restore access
Cleanup¶
Periodically review keys:
- Check lastUsedUtc timestamp
- Revoke keys unused for 30+ days
- Confirm with integration owners before revoking
Security Best Practices¶
Storage¶
Advise integration partners to: - Store keys in environment variables or secret managers - Never commit keys to source control - Avoid hardcoding in scripts or configuration files
Key Separation¶
Create separate keys for: - Different integrations (Zapier vs HubSpot) - Different use cases (read-only vs write) - Development vs production (if applicable)
Separate keys allow targeted revocation without disrupting other integrations.
Monitoring¶
Last Used Timestamp¶
The lastUsedUtc field shows when the key was last used. Check this to:
- Identify dormant keys for cleanup
- Confirm integrations are actively running
- Detect unexpected usage
Rate Limit Tracking¶
The lastUsedUtc field helps identify active vs dormant keys. For detailed rate limit consumption metrics, contact your account administrator.
Troubleshooting¶
Key Not Working After Creation¶
Symptom: 401 responses immediately after creating key
Check:
- Key was copied completely (no truncation)
- X-Api-Key header is set correctly
- API endpoint URL is correct
Key Stops Working Suddenly¶
Symptom: Previously working key returns 401
Causes: - Key was revoked - Key was deleted from Admin Portal
Resolution: - Check key status in Admin Portal - Create new key if revoked - Update external system with new key
Insufficient Scope Errors¶
Symptom: 403 responses for specific operations
Resolution: - Check required scopes in error-handling.md - Create new key with additional scopes - Cannot add scopes to existing keys