API Key Management
The Calcs.com Developer Portal provides a comprehensive API key management interface that allows you to create, view, update, and delete API keys for accessing the Calcs.com API.
Accessing API Key Management
Once authenticated, you can access the API Key Management interface at:
Code
Features
Create API Keys
Generate new API keys with optional descriptions and expiration dates. Each key is automatically linked to your authenticated user account.
Key Features:
- Custom Descriptions: Add meaningful descriptions to identify different keys
- Optional Expiration: Set expiration dates for enhanced security
- Instant Generation: Keys are created immediately and ready to use
- Metadata Tracking: Each key stores your user ID and email for auditing
View Your API Keys
See all your active API keys in one place, including:
- Key ID (for reference)
- Key value (for authentication)
- Description
- Creation date
- Expiration date (if set)
Regenerate Keys (Roll)
If a key is compromised or you need to rotate it for security:
- Select the key you want to regenerate
- Click "Roll Key"
- A new key value is generated while maintaining the same key ID and metadata
This is useful for:
- Security rotations
- Responding to potential compromises
- Regular key refresh policies
Delete Keys
Remove API keys that are no longer needed:
- Select the key to delete
- Confirm deletion
- The key is immediately revoked and cannot be used for API access
Warning: Deleted keys cannot be recovered. Any applications using deleted keys will immediately lose access.
Usage in API Requests
Once you have created an API key, use it in your API requests with the Bearer token authentication scheme:
cURL Example
Code
JavaScript Example
Code
Python Example
Code
Best Practices
Security
- Never commit API keys to version control
- Use environment variables to store keys in your applications
- Rotate keys regularly using the Roll feature
- Set expiration dates for keys used in temporary projects
- Delete unused keys to minimize security surface
Organization
- Use descriptive names that identify the key's purpose
- One key per application for better tracking and revocation
- Document key usage in your team's internal documentation
Integration
- Store keys securely in environment variables or secret management systems
- Handle key rotation gracefully in your applications
- Monitor key usage through the portal's usage tracking (if available)
Metadata
Each API key includes metadata that links it to the ClearCalcs platform:
clearcalcsApiToken: Your ClearCalcs user API token (if configured)clearcalcsOrganisationId: Your organization ID (if applicable)customerId: Your Auth0 user IDcreatedBy: Your email address
This metadata enables seamless integration between the developer portal and the ClearCalcs platform.
Troubleshooting
"Failed to fetch consumers"
This error occurs when the API key service cannot retrieve your keys. Check that:
- Your authentication is valid
- The Zuplo configuration is correct
- You have network connectivity
"API key not configured with ClearCalcs credentials"
This means the API key exists but lacks ClearCalcs integration metadata. Contact support to configure the integration.
Keys not appearing
If your keys aren't showing up:
- Ensure you're logged in with the correct account
- Check that the keys were created successfully
- Refresh the page
- Clear your browser cache
Support
For help with API key management:
- Visit Calcs.com Support
- Check the API Documentation
- Review the Authentication Guide