Integrating Securely with the SDK

How the EgoX SDK authenticates, signs and verifies tool calls, forwards headers safely, and keeps your integration trustworthy.

The @egox/client SDK is the recommended way to integrate. Beyond convenience, it exists to make the secure path the default one. This page covers the security-relevant parts of an integration.

Authenticating requests

API key over TLS. The SDK sends your project API key (egox_live_… / egox_test_…) as X-API-Key over HTTPS. Keep it server-side — never ship it to a browser or mobile client.
Test vs live keys. Use egox_test_… for development so test traffic is clearly separated from production.
Type-safe wire contracts. The SDK's request/response types come from @egox/contracts — the same package the backend uses — so a field change on the server becomes a compile error in your build instead of a silent runtime bug.

import { EgoX } from '@egox/client';

const egox = new EgoX({
  apiKey: process.env.EGOX_API_KEY,     // server-side only
  tenantId: process.env.EGOX_TENANT_ID,
});

Verifying tool calls (signed webhooks)

When the LLM triggers a tool, EgoX calls your endpoint — so your endpoint must be able to tell a genuine EgoX request from a forged one. Every call is signed:

Header	Purpose
`X-EgoX-Signature`	HMAC-SHA256 of the body (`sha256=…`)
`X-EgoX-Timestamp`	Unix timestamp — bounds replay
`X-EgoX-Request-Id`	Correlation id for debugging
`X-EgoX-Tenant-Id`	Your project id

Always verify

Verify the signature and the timestamp on every tool request. The SDK ships an Express middleware and standalone helpers so you don't hand-roll the HMAC — see Webhook signature verification.

import { createEgoXMiddleware } from '@egox/client/express';

const verifyEgoX = createEgoXMiddleware({
  secret: process.env.EGOX_WEBHOOK_SECRET,
  tolerance: 300, // reject requests older than 5 min (replay defense)
});

app.post('/api/tools/check-order', verifyEgoX, (req, res) => {
  // request is authenticated — safe to act
  res.json({ status: 'Order shipped' });
});

Forwarding context safely

Tools often need per-request context (a user id, locale, or the caller's token). EgoX gives you three explicit channels, each with guardrails so nothing leaks by accident:

Field	Carries	Guardrail
`authToken`	the caller's user token → forwarded as `Authorization: Bearer …` to your tool	goes only to tools whose `authType` is `FORWARD`
`headers`	trusted, server-set HTTP headers (locale, app version, gateway user id)	only names on the tool's `forwardHeaders` allowlist are passed through
`toolHeaders`	per-end-user secrets destined for the tool	sent on the request body, so it can't collide with EgoX's own auth headers

Two protections apply automatically:

Sensitive headers are blocked server-side — Cookie, Host, Authorization, X-Api-Key, X-Tenant-Id, and similar are never forwarded from inbound /ask requests.
SDK-reserved names are stripped before forwarding (the full list is exported as SDK_RESERVED_HEADERS), so platform credentials can't leak into a tool call.

Only headers you explicitly add to a tool's forwardHeaders allowlist in the Console reach that tool. The default is to forward nothing.

Resilience by default

Timeouts and bounded retries with exponential backoff are built in (configurable), so a slow or flaky upstream doesn't hang your request path.
Typed errors (AuthenticationError, ValidationError, RateLimitError, TimeoutError, NetworkError, EgoXError) let you branch on failure precisely instead of parsing strings — see Error handling.

Checklist

Store EGOX_API_KEY and EGOX_WEBHOOK_SECRET as server-side secrets.
Verify X-EgoX-Signature and timestamp on every tool endpoint.
Add only the headers you need to each tool's forwardHeaders allowlist.
Use egox_test_… keys in non-production environments.