Authentication

Two ways to call the API

• No key (test mode). /calculate/electricity, /calculate/fuel and /calculate/flight answer without any header, limited per IP address.
• API key. Send Authorization: Bearer zc_.... Required for /calculate/spend; on the other endpoints it moves you to the per-company limit.

Getting an API key

API keys are issued to companies whose plan includes API access (Enterprise plans, or Professional with an API add-on).

1. Sign in and open API Keys in your dashboard.
2. Click Generate New API Key.
3. Copy the key. It starts with zc_live_ and is shown only once: only a hash is stored.

Sending the key

Put the key in the Authorization header with the Bearer scheme:

curl -X POST https://zerocarbon.org.in/api/v1/calculate/spend \
  -H "Authorization: Bearer $ZEROCARBON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50000, "currency": "INR", "category": "metals"}'

const res = await fetch('https://zerocarbon.org.in/api/v1/calculate/spend', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ZEROCARBON_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ amount: 50000, currency: 'INR', category: 'metals' }),
});
console.log(res.status, await res.json());

A key that is sent but not valid is rejected; the request does not fall back to test mode.

Rate limits

Test-mode responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Over the limit you get 429; wait until the reset time and retry.

Authentication errors

{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" }
}

• Missing or invalid API key - /calculate/spend called without a key
• Invalid API key - the key is wrong or has been revoked