The Gateway is spec-first — built around OpenAPI 3.1. A full publishable spec will be linked here once it's available. Until then, this page covers the authentication model, rate limits, and webhook integration — the things you need before touching an endpoint.
All API calls require a Bearer token issued via the workspace API key. Tokens are scoped to a workspace and carry the organisation's permission set. Short-lived access tokens (1 hour TTL) are issued by exchanging the API key; refresh is handled automatically by the client SDK.
The API Gateway enforces per-workspace rate limits. Standard tier: 1,000 requests/minute. Enterprise tier: configurable, negotiated at onboarding. Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are returned on every response.
Subscribe to platform events (passport.issued, event.recorded, verification.completed) via the webhook registry in your workspace settings. Every delivery is signed with HMAC-SHA256 using your webhook secret — validate the X-TierraTrace-Signature header before processing.
The signature is computed over the raw request body. Compute HMAC-SHA256(secret, body) and compare it to the signature value (after stripping the 'sha256=' prefix). Use a constant-time comparison to prevent timing attacks. Reject any delivery where the signature doesn't match.
High-throughput integrations can use the streaming endpoint instead of webhooks. The stream uses Server-Sent Events (SSE) and delivers a chronologically ordered sequence of supply chain events for a given product, workspace, or filter set.
Official SDKs are available for Node.js and Python, covering authentication, event recording, passport issuance, and webhook validation. Community SDKs for Go and Java are in progress. All SDKs are built against the OpenAPI 3.1 spec.
Exchange your API key for an access token, then authenticate requests.
1. Get an access token
curl -X POST https://api.tierratrace.in/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"api_key": "tt_live_••••••••••••"
}'
# Response
{
"access_token": "eyJ...",
"expires_in": 3600,
"token_type": "Bearer"
}2. Record a supply chain event
curl -X POST https://api.tierratrace.in/v1/events \
-H "Authorization: Bearer eyJ..." \
-H "Content-Type: application/json" \
-d '{
"product_id": "tt-prod-abc123",
"type": "manufacture.complete",
"location": "Tiruppur, Tamil Nadu",
"metadata": {
"batch": "#KNT-8812",
"co2e_kg": 20.1
}
}'3. Validate a webhook signature
import hmac, hashlib
def is_valid_signature(payload_body: bytes, secret: str, header: str) -> bool:
expected = hmac.new(
secret.encode(), payload_body, hashlib.sha256
).hexdigest()
received = header.removeprefix("sha256=")
return hmac.compare_digest(expected, received)Building an integration? For enterprise integration details including ERP connectors, see TierraTrace Connect. For early API access or a private spec preview, email info@namolabs.in.