Overview

EdgeKit Client API 1.0.0

The API clients use to interact with EdgeKit.

The browser-facing paths are also served under the /edgekit namespace, for organizations that proxy this API from their own domain behind a single /edgekit/* rule: /v1/id (except /v1/id/upstream/*), /v1/org, /v1/grants, /v1/newsletters/lists and /v1/newsletters/subscriptions. Both mounts are equal and neither is deprecated. Every API-key route is served on /v1 only, and so are the emailed newsletter links. /edgekit/v1/recommendations is not an alias of the keyed /v1/recommendations: it is the browser’s own mount, with its own credential.

/edgekit/v1/checkout is the one path with no /v1 twin. Its caller is always a browser on the organization’s own domain, and an organization with a backend already holds its own billing-provider key.

A session works on both mounts: its cookie is scoped to /, so signing in on one mount authenticates the other. A URL this API generates, such as an emailed magic link, carries the prefix of the request that minted it, so a user who signed in through the proxy is sent back through the proxy.

Authentication

Three credential types, never mixed on one route:

User session: a cookie (ek.session_token), minted by the sign-in routes under ID. Read by the ID routes that act on the signed-in user, by Organizations and Grants, and by the browser decide mount. A native client may instead present the set-auth-token value it was issued as Authorization: Bearer <session token>. A browser cannot: that header is not on this API’s CORS allowlist, and the token is not exposed to cross-origin JavaScript.
API key: Authorization: Bearer <key> or x-api-key, pinned to one site. Used server-to-server: the keyed /v1/decide mount, /v1/id/upstream/*, schema resolution under /v1/iglu, /v1/content/sync and /v1/recommendations.

A credential presented on the wrong route group is refused, not reinterpreted: an API key on a user-session route, or a session cookie on a key-only route, always fails.

Sites & headers

Every request below selects a site with the x-edgekit-site-id header. Every official EdgeKit SDK sets it for you from the client you configure; set it yourself only when calling this API directly. A request missing it returns 400.

GET /v1/id/config and GET /v1/id/traits skip per-origin CORS: they answer Access-Control-Allow-Origin: * and vary their cache on the header rather than on Origin. Neither carries a credential, so each site stays one cache entry across every origin that reads it.

The session cookie is not site-scoped: it is set with Path=/ for the whole tenant, so a valid session does not say which site a request is for; the header selects the site.

/v1/decide, /v1/gift-links and the interventions stream are documented separately, at /v1/decide/openapi.json.

Versioning

v1 changes only additively. A client must therefore:

ignore unknown response fields, and accept an unknown member of any response enum: every enum below is open;
expect an unknown request field to be ignored, never refused. The one exception is POST /edgekit/v1/checkout, whose body is an allowlist (a stray key may be card data);
branch on error.code and the status only. code is an open string, with the known set listed per operation. error.details is unstable in v1: log it, never parse it;
honour Retry-After: every 429 and every retryable 503 carries it. A 503 without it means the capability is not configured, and a retry will not help.

Information

OpenAPI version: 3.1.0

Authentication

ApiKeyAuth

A site-pinned API key issued by EdgeKit. Server-to-server only — never reachable from a browser.

Security scheme type: http

ApiKeyHeader

The ApiKeyAuth key, sent as x-api-key instead.

Security scheme type: apiKey

Header parameter name: x-api-key

UserSession

A user’s own session. Accepted only on the identity surface; a key is never accepted there, and this is never accepted on a key-authenticated route.

Security scheme type: apiKey

Cookie parameter name: ek.session_token

Overview

EdgeKit Client API 1.0.0

Authentication

Sites & headers

Versioning

Operations

Authentication

ApiKeyAuth

ApiKeyHeader

UserSession