Authentication

The ekko REST API is served over HTTPS and follows standard security practices. Requests use resource-oriented URLs, accept JSON-encoded bodies, return JSON responses, and follow conventional HTTP verbs and status codes.

All requests require an API key, which you generate in ekkoHub. Pass the key in the X-Api-Key header on every call:

X-Api-Key: YOUR_API_KEY

Your API key is validated on each request to ensure only authorised access.

⚠️
Keep your API keys safe:

Store them securely (for example, in environment variables or a secrets manager)

Never expose them in client-side code or public repositories

Rotate them regularly on ekko Hub

Error handling

The ekko API uses standard HTTP status codes to indicate success or failure.

Error	Description
`401 Unauthorised`	Invalid or missing `X-Api-Key`
`400 Bad Request`	Missing or incorrect parameters
`404 Not found`	Resource not found
`500 Internal Server Error`	An unexpected error on ekko’s side

Error responses include structured details to help you debug:

Field	Description	Type
`statusCode`	HTTP status code	Integer
`name`	Specific name of the error	String
`message`	General description of the error	String
`details`	Additional context (validation errors, constraints)	Object
`details.message`	List of validation error messages	Array of strings
`details.error`	More specific error category	String
`path`	The endpoint path that failed	String
`requestId`	Unique reference ID for tracing the request	String
`timestamp`	When the request occurred	String

Example errors:

{
    "error": {
        "statusCode": 400,
        "message": "Bad Request Exception",
        "errorName": "BadRequestException",
        "details": {
            "message": [
                "amount.value must be a positive number",
                "amount.value should not be empty",
                "amount.value must be a number conforming to the specified constraints"
            ],
            "error": "Bad Request",
            "statusCode": 400
        },
        "path": "/v2.5/impact_calculator",
        "requestId": "7AkD3H",
        "timestamp": "2025-09-09T16:51:00.789Z"
    }
}

{
    "error": {
        "statusCode": 404,
        "message": "Carbon data not found for MCC: 54992 and country: GBR",
        "errorName": "_NotFoundException",
        "details": "Carbon data not found for MCC: 54992 and country: GBR",
        "path": "/v2.5/impact_calculator",
        "requestId": "qnYFPF",
        "timestamp": "2025-09-09T16:52:10.413Z"
    }
}

IP allowlisting

For additional security, you can restrict access to ekko endpoints using IP allowlisting.

Log into ekko Hub
Go to Console → IP allowlisting
Add one or more IP addresses, ranges, or CIDR blocks
Enable allowlisting using the toggle at the top

Once enabled, only requests from approved IPs will be accepted.

For more detail, see the section on ekko Hub.