Authentication

Overview

The ZeroCarbon API uses API keys for authentication. All API requests must include an API key in the Authorization header using the Bearer authentication scheme.

Getting an API Key

Once you have an eligible plan:

1. Log in to app.zerocarbon.org.in
2. Navigate to Settings → Billing → API Keys
3. Click "Create New API Key"
4. Choose Test (zc_test_) or Live (zc_live_) mode
5. Give your key a descriptive name (e.g., "Production API", "Development")
6. Copy the generated key immediately (it will only be shown once)

Making Authenticated Requests

Include your API key in every request using the Authorization header:

cURL Example

curl https://api.zerocarbon.org.in/v1/company/dashboard \
  -H "Authorization: Bearer zc_live_abc123xyz789..." \
  -H "Content-Type: application/json"

Node.js / TypeScript

import { ZeroCarbon } from 'zerocarbon-nodejs-sdk';
import * as dotenv from 'dotenv';

dotenv.config();

const client = new ZeroCarbon({
  apiKey: process.env.ZEROCARBON_API_KEY!,
  baseUrl: 'https://api.zerocarbon.org.in/v1'
});

// SDK automatically includes the Authorization header
const dashboard = await client.dashboard.get();

Python

import os
from zerocarbon import ZeroCarbon
from dotenv import load_dotenv

load_dotenv()

client = ZeroCarbon(
    api_key=os.getenv('ZEROCARBON_API_KEY'),
    base_url='https://api.zerocarbon.org.in/v1'
)

# SDK automatically includes the Authorization header
dashboard = client.dashboard.get()

Raw HTTP Request

const response = await fetch('https://api.zerocarbon.org.in/v1/company/dashboard', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.ZEROCARBON_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

API Key Types

ZeroCarbon provides different types of API keys for different environments:

API Add-on Packs (Professional Plan)

If you're on the Professional Plan, you must purchase one of the following API add-on packs:

Enterprise Plan: Includes unlimited API keys with full access to all endpoints—no need to purchase add-ons.

Security Best Practices

Use Environment Variables

Never hardcode API keys in your source code. Use environment variables instead:

# .env file (add to .gitignore!)
ZEROCARBON_API_KEY=zc_live_abc123xyz789...

Rotate Keys Regularly

Periodically rotate your API keys for better security. Create a new key and update your application before deleting the old one to avoid downtime.

Use Different Keys per Environment

Use separate API keys for development, staging, and production environments. This allows you to rotate keys without affecting other environments.

Restrict Key Permissions

When creating API keys, you can optionally restrict them to specific IP addresses or domains for added security.

Authentication Errors

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "status": 401
  }
}

Common authentication errors:

• INVALID_API_KEY - API key is malformed or doesn't exist
• API_KEY_REVOKED - API key has been deleted or revoked
• API_KEY_EXPIRED - API key has expired (if set with expiration)
• RATE_LIMIT_EXCEEDED - Too many requests (see Rate Limiting)