Authentication¶

Emmi API supports two authentication models:

Single Tenant - For organizations using the API for their own internal purposes - One API key per account - All usage attributed to your organization - Tiered pricing based on consumption

Multi-Tenant - For platforms serving multiple end-customers - One platform API key - Usage attributed per end-customer via headers

Contact support@emmi.io to receive your API key.

Single Tenant Authentication¶

Single tenant API keys are designed for organizations that integrate directly with the Emmi API for their own internal use.

API Key Format¶

Single tenant API keys follow this format:

sk_live_single_{random}_{checksum}

Components: - sk - Secret key prefix - live - Environment (live for production, test for sandbox) - single - Tenant type - {random} - Random string for uniqueness - {checksum} - Validation checksum

Making Authenticated Requests¶

Include your API key in the X-API-Key header with every request:

Example Request¶

curl -X POST https://app.emmi.io/api/v1/emissions-estimates \
  -H "X-API-Key: sk_live_single_4n8jKmPqRs9uVw_8f1c" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_info": {
      "identifier": "EXMPL",
      "name": "Example Corp",
      "asset_type": "equity",
      "country": "United States",
      "industry_classification_system": "rbics",
      "industry": "Technology",
      "sector": "Software"
    },
    "data": [
      {
        "year": 2023,
        "financials": {
          "currency": "USD",
          "revenue": 5000000000
        }
      }
    ]
  }'

Multi-Tenant Authentication¶

Multi-tenant API keys are designed for platforms that integrate with the Emmi API once and then provide climate risk and emissions analysis functionality to their own customers.

API Key Format¶

Multi-tenant API keys follow this format:

sk_live_multi_{random}_{checksum}

Components: - sk - Secret key prefix - live - Environment (live for production, test for sandbox) - multi - Tenant type - {random} - Random string for uniqueness - {checksum} - Validation checksum

End-User Attribution¶

The X-End-User-Id Header¶

Multi-tenant customers must include the X-End-User-Id header in every API request to identify which end-customer the request is for:

X-End-User-Id: customer_abc_123

This header: - Required for all multi-tenant API requests - Enables usage tracking per end-customer - Allows per-customer rate limiting - Provides detailed usage analytics - Supports your own customer billing

End-User ID Format¶

End-user IDs should be: - Unique within your platform - Stable over time (don't change for the same customer) - Alphanumeric with underscores and hyphens allowed - Maximum 255 characters

Recommended format:

customer_{your_customer_id}

Making Authenticated Requests¶

Include both the X-API-Key header (with your multi-tenant key) and the X-End-User-Id header (with your customer's identifier):

Example Request¶

curl -X POST https://app.emmi.io/api/v1/emissions-estimates \
  -H "X-API-Key: sk_live_multi_7x9mK3pQrS6uVw_c4a2" \
  -H "X-End-User-Id: customer_abc_123" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_info": {
      "identifier": "EXMPL",
      "name": "Example Corp",
      "asset_type": "equity",
      "country": "United States",
      "industry_classification_system": "rbics",
      "industry": "Technology",
      "sector": "Software"
    },
    "data": [
      {
        "year": 2023,
        "financials": {
          "currency": "USD",
          "revenue": 5000000000
        }
      }
    ]
  }'