Authentication

The emissions.dev API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Getting Your API Key

1. Sign up at emissions.dev
2. Go to your Dashboard
3. Navigate to API Keys
4. Click Create API Key
5. Copy your key (it won't be shown again!)

Using Your API Key

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

Authorization: Bearer em_live_xxxxxxxxxxxx

Example Request

curl https://api.emissions.dev/v1/freight/emissions \
  -H "Authorization: Bearer em_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

JavaScript Example

const response = await fetch('https://api.emissions.dev/v1/freight/emissions?origin_country=GB&destination_country=FR&weight=1000', {
  headers: {
    'Authorization': 'Bearer ' + process.env.EMISSIONS_API_KEY
  }
});
const data = await response.json();

Python Example

import requests

response = requests.get(
    'https://api.emissions.dev/v1/freight/emissions',
    params={
        'origin_country': 'GB',
        'destination_country': 'FR',
        'weight': 1000
    },
    headers={
        'Authorization': f'Bearer {api_key}'
    }
)
data = response.json()

PHP Example

$response = Http::withToken($apiKey)
    ->get('https://api.emissions.dev/v1/freight/emissions', [
        'origin_country' => 'GB',
        'destination_country' => 'FR',
        'weight' => 1000,
    ]);

$data = $response->json();

API Key Types

Security Best Practices

Never expose keys in client-side code

// DON'T do this - key is exposed!
const response = await fetch('https://api.emissions.dev/v1/...', {
  headers: { 'Authorization': 'Bearer em_live_xxxxxxxxxxxx' }
});

// DO this - call from your backend
const response = await fetch('/api/calculate-emissions', {
  method: 'POST',
  body: JSON.stringify({ origin: 'GB', destination: 'FR', weight: 1000 })
});

Use environment variables

# .env
EMISSIONS_API_KEY=em_live_xxxxxxxxxxxx

Authentication Errors

Example error response:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key. Get your key at https://emissions.dev/dashboard",
    "status": 401
  }
}