Getting Started

Copy page

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
 
/settings/api-keys

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:

1. Select the key you want to regenerate
2. Click "Roll Key"
3. 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:

1. Select the key to delete
2. Confirm deletion
3. 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
 
curl -X GET "https://api.calcs.com/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript Example

Code
 
const response = await fetch('https://api.calcs.com/v1/projects', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

Python Example

Code
 
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('https://api.calcs.com/v1/projects', headers=headers)

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 ID
• createdBy: 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:

1. Ensure you're logged in with the correct account
2. Check that the keys were created successfully
3. Refresh the page
4. Clear your browser cache

Support

For help with API key management:

• Visit Calcs.com Support
• Check the API Documentation
• Review the Authentication Guide