Carbon Interface Authentication: API Key & Security Guide

Authentication overview

Carbon Interface secures its API endpoints using API keys. This method requires developers to include a unique, secret key with each request to authenticate their identity and authorize access to the service's functionalities, such as calculating carbon emissions for flights, shipping, or electricity consumption. The API key serves as a credential that links requests back to a specific user account, enabling usage tracking and adherence to rate limits and subscription plans.

The API key is a long, randomly generated string that should be treated as sensitive information. It grants access permissions associated with the account that generated it. Misuse or exposure of an API key can lead to unauthorized access, potential security breaches, and unexpected charges on paid plans. Carbon Interface's approach aligns with common practices for RESTful APIs where API keys provide a straightforward mechanism for client authentication without requiring complex session management or token exchange flows.

Supported authentication methods

Carbon Interface primarily supports API key authentication. This method is suitable for server-to-server communication and backend applications where the API key can be securely stored and managed. It provides a balance of security and ease of implementation for developers integrating carbon emission data into their applications.

API keys are transmitted via the Authorization HTTP header as a Bearer token. This is a standard method for sending access tokens in HTTP requests, as described in RFC 6750 for Bearer Token Usage. The key should always be sent over HTTPS to prevent interception during transit, ensuring that the communication channel is encrypted.

Getting your credentials

To obtain your Carbon Interface API key, you need to sign up for an account on their platform. The process typically involves:

1. Account Creation: Navigate to the Carbon Interface homepage and sign up for a new account. A free Developer tier is available, offering 50 requests per month.
2. Dashboard Access: Once registered and logged in, you will be directed to your Carbon Interface dashboard.
3. API Key Generation/Retrieval: Within the dashboard, there will be a section dedicated to API keys or developer settings. Here, you can generate a new API key or retrieve an existing one. Carbon Interface's official documentation provides specific instructions on navigating the dashboard to find your API key.
4. Key Management: The dashboard also allows for managing your API keys, including options to revoke old keys and generate new ones, which is a crucial security practice.

It is critical to copy your API key immediately upon generation and store it securely. Unlike passwords, API keys are often displayed only once upon creation for security reasons and cannot be retrieved if lost. If a key is lost, a new one must be generated and the old one revoked.

Authenticated request example

Authenticated requests to the Carbon Interface API include the API key in the Authorization header using the Bearer token scheme. Below are examples demonstrating how to include your API key in requests using cURL and Python.

cURL Example

This cURL example demonstrates a request to the Carbon Interface API's electricity estimate endpoint, including the Authorization header with a placeholder for your API key.

curl -X POST \
  https://www.carboninterface.com/api/v1/estimates \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "electricity",
    "electricity_unit": "kwh",
    "electricity_value": 200,
    "country": "us"
  }'

Python Example

This Python example uses the requests library to make a similar API call, demonstrating how to construct the headers programmatically.

import requests
import json

api_key = "YOUR_API_KEY"
url = "https://www.carboninterface.com/api/v1/estimates"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

payload = {
    "type": "electricity",
    "electricity_unit": "kwh",
    "electricity_value": 200,
    "country": "us"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))

if response.status_code == 201:
    print("Estimate created successfully:")
    print(json.dumps(response.json(), indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")

For more detailed API usage examples across different endpoints and programming languages, refer to the comprehensive Carbon Interface API reference documentation.

Security best practices

Securing your API keys is paramount to protect your account and prevent unauthorized usage. Adhering to these best practices reduces the risk of credential compromise:

• Treat API Keys as Sensitive Credentials: Your API key provides direct access to your Carbon Interface account. Treat it with the same level of security as a username and password.
• Environment Variables: Store API keys in environment variables rather than hardcoding them directly into your application's source code. This practice prevents keys from being exposed in version control systems (like Git repositories) and allows for easier rotation across different deployment environments (development, staging, production). For instance, in Python, you might use os.environ.get("CARBON_INTERFACE_API_KEY").
• Secure Configuration Files: If environment variables are not feasible, use secure configuration management tools or encrypted secrets files. Ensure these files are excluded from version control and have restricted access permissions.
• Server-Side Use Only: Never expose your API key in client-side code (e.g., JavaScript in a web browser or mobile application). Client-side code is susceptible to interception and reverse engineering, which would expose your key to end-users and potential attackers. All calls to Carbon Interface should originate from your secure backend server.
• HTTPS/TLS Enforcement: Always transmit API keys over HTTPS (HTTP Secure) to encrypt communication and protect the key from interception during transit. The Carbon Interface API inherently enforces HTTPS for all requests, but it's important to ensure your client also uses HTTPS.
• IP Whitelisting (if available): If Carbon Interface offers IP whitelisting, configure it to allow API calls only from a predefined list of trusted server IP addresses. This adds an extra layer of security, ensuring that even if a key is compromised, it can only be used from authorized locations. Check the Carbon Interface documentation for details on whether this feature is supported.
• Regular Key Rotation: Periodically rotate your API keys. If a key is compromised, rotating it minimizes the window of exposure. Carbon Interface's dashboard should provide functionality to revoke old keys and generate new ones.
• Monitor Usage: Regularly monitor your API usage through the Carbon Interface dashboard. Unusual spikes in activity or requests from unexpected locations could indicate a compromised key.
• Error Handling: Implement robust error handling in your application to manage authentication failures gracefully without exposing sensitive information.
• Least Privilege: If Carbon Interface introduces granular permissions for API keys in the future, configure keys with the minimum necessary permissions required for the task they perform. This limits the damage if a key is compromised.

Adhering to these security practices helps maintain the integrity of your integration with Carbon Interface and protects your data and account resources.