Authentication overview

Climatiq is a platform that provides access to a comprehensive database of carbon emissions factors and an API for calculating carbon footprints. Secure access to Climatiq's API is managed through API key authentication. This mechanism allows developers and applications to interact with the API endpoints, such as retrieving emissions factors or performing calculations, by presenting a unique, secret key with each request.

The API key serves as a unique identifier for your application and authenticates your requests, ensuring they are associated with your Climatiq account. This setup allows Climatiq to track API usage, enforce rate limits, and apply access permissions based on your subscription plan. All API communication is secured using HTTPS/TLS, encrypting data in transit and protecting your API key from interception. For detailed API specifications, refer to the Climatiq API reference documentation.

Integrating Climatiq's API into applications, especially for ESG reporting automation or supply chain emissions calculations, requires a clear understanding of its authentication flow. The API key approach is a common and effective method for authenticating server-to-server or backend applications accessing external services, as described in general principles for API security on sites like the Twilio API security glossary.

Supported authentication methods

Climatiq primarily supports API key authentication. This method involves generating a unique string from your Climatiq account dashboard, which is then included in the authorization header of every API request.

Climatiq's API keys are designed for simplicity and direct integration. They are associated with your user account and provide direct access to the API within the scope of your subscription plan (e.g., the Developer Plan offers 50,000 API credits/month). There are no complex OAuth 2.0 flows or multi-factor authentication mechanisms required for API access itself, streamlining the integration process for backend applications.

API Key

The API key is a secret token that grants access to the Climatiq API. When you make a request, you include this key in the Authorization header, prefixed with Bearer. This signifies to the Climatiq server that the request is authorized and originating from your account.

  • When to use: Ideal for server-side applications, backend services, or scripts that directly call the Climatiq API where the API key can be securely stored and managed. It is suitable for automated data retrieval or emissions calculation tasks.
  • Security level: Moderate to High, depending on key management. Secure storage and regular rotation are critical. HTTPS/TLS encryption protects the key during transit.

The table below summarizes the supported authentication method:

Method When to Use Security Level
API Key Backend services, server-side applications, scripts needing direct API access. Moderate (dependent on secure storage and transmission via HTTPS).

Getting your credentials

To obtain your Climatiq API key, you need to sign up for a Climatiq account and navigate to your developer dashboard. The process typically involves these steps:

  1. Sign Up/Log In: Go to the Climatiq homepage and either create a new account or log in to an existing one. A free Developer Plan is available, offering 50,000 API credits per month, which includes API access.
  2. Access Dashboard: Once logged in, locate the developer or API section within your account dashboard. This area is specifically designed for managing your API settings and credentials.
  3. Generate API Key: Within the API section, there should be an option to generate or view your API key. Climatiq provides a single, primary API key for your account by default.
  4. Copy Key: Carefully copy the generated API key. It is a long string of alphanumeric characters. Treat this key as a sensitive secret.
  5. Store Securely: Store your API key in a secure location. Avoid hardcoding it directly into your application's source code, especially for public repositories. Environment variables or a secure configuration management system are recommended for production environments.

For explicit instructions and visual guides, always refer to the official Climatiq documentation on API key management.

Authenticated request example

Once you have your API key, you can use it to make authenticated requests to the Climatiq API. The key must be included in the Authorization header of your HTTP request, prefixed with Bearer. Below are examples in Python and Node.js, reflecting Climatiq's primary language example support for developers.

Python example

Using the requests library to make a POST request to calculate emissions:

import requests
import os

# It's recommended to store your API key as an environment variable
CLIMATIQ_API_KEY = os.environ.get("CLIMATIQ_API_KEY")

if not CLIMATIQ_API_KEY:
    raise ValueError("CLIMATIQ_API_KEY environment variable not set.")

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

data = {
    "emission_factor": {
        "id": "passenger_car-fuel_type_petrol-engine_size_na-vehicle_age_na-composite_gb"
    },
    "parameters": {
        "distance": 100,
        "distance_unit": "km"
    }
}

try:
    response = requests.post(
        "https://api.climatiq.io/data/v1/estimate",
        headers=headers,
        json=data
    )
    response.raise_for_status() # Raise an exception for HTTP errors
    print(response.json())
except requests.exceptions.HTTPError as e:
    print(f"HTTP error occurred: {e}")
    print(f"Response body: {response.text}")
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Node.js example

Using fetch (available in modern Node.js versions) or axios to make a similar request:

const fetch = require('node-fetch'); // For older Node.js environments

// It's recommended to store your API key as an environment variable
const CLIMATIQ_API_KEY = process.env.CLIMATIQ_API_KEY;

if (!CLIMATIQ_API_KEY) {
  throw new Error("CLIMATIQ_API_KEY environment variable not set.");
}

async function getCarbonEstimate() {
  const headers = {
    "Authorization": `Bearer ${CLIMATIQ_API_KEY}`,
    "Content-Type": "application/json"
  };

  const data = {
    "emission_factor": {
      "id": "passenger_car-fuel_type_petrol-engine_size_na-vehicle_age_na-composite_gb"
    },
    "parameters": {
      "distance": 100,
      "distance_unit": "km"
    }
  };

  try {
    const response = await fetch("https://api.climatiq.io/data/v1/estimate", {
      method: "POST",
      headers: headers,
      body: JSON.stringify(data)
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`HTTP error! Status: ${response.status}, Details: ${errorText}`);
    }

    const result = await response.json();
    console.log(result);
  } catch (error) {
    console.error("Error fetching carbon estimate:", error);
  }
}

getCarbonEstimate();

Security best practices

Adhering to security best practices when handling API keys is crucial to prevent unauthorized access to your Climatiq account and data. Climatiq's API key mechanism is robust when managed correctly.

  1. Keep API Keys Secret: Treat your API key as a password. Never hardcode it directly into client-side code (e.g., JavaScript in a browser) or commit it directly to version control systems like Git, especially public repositories.
  2. Use Environment Variables: Store API keys in environment variables on your server or build system. This keeps them out of your codebase and makes it easier to manage different keys for different environments (development, staging, production). For instance, the AWS documentation on access key best practices provides general guidance applicable to any API key.
  3. Restrict Access: Limit access to your API keys to only those individuals or systems that absolutely need them. Implement strong access controls for your servers and development environments where keys are stored.
  4. Rotate Keys Regularly: Periodically generate new API keys and revoke old ones. This minimizes the risk window if a key is compromised. The Climatiq dashboard should provide functionality for key rotation.
  5. Monitor Usage: Regularly review your Climatiq API usage logs for any unusual activity. Spikes in requests or requests from unexpected geographical locations could indicate a compromised key.
  6. Secure Communication: Always ensure that all API requests are made over HTTPS (Transport Layer Security - TLS). Climatiq's API strictly enforces HTTPS, which encrypts your API key and request data in transit, protecting it from interception.
  7. Error Handling: Implement robust error handling in your application to gracefully manage authentication failures. Avoid exposing raw API keys or sensitive error messages to end-users.
  8. Avoid Public Exposure: Never embed your API key directly into URLs or expose it in publicly accessible client-side code. This makes the key vulnerable to theft.

By following these best practices, you can significantly enhance the security posture of your applications integrating with the Climatiq API and protect your carbon emissions data.