Get started

Do these steps in order, once for each site. Steps 2 to 5 link to the Delivery pages with the detail.

The steps that change a site, and the deploy, need the Owner or Admin role. A Developer can stage a change but cannot deploy it or change a site.

1. Open your organization’s account

There is no self-serve sign-up. Book a demo, and EdgeKit opens your organization’s account. Your organization gets its own database and its own sign-in instance, and shares neither with any other organization.

When EdgeKit sets up your organization, it also creates your first site from the name, domain and browser origins you give it. You get your tenant host: the hostname your organization’s API answers on, for example edgekit.example.com. These docs write it as your-tenant-host.

2. Check your site

Open your site from Delivery › Delivery › Sites. The console has no action that adds a site, so your first site is already in the list. Check its settings:

• Domain: the hostname only, with no scheme, port or path.
• Status: active. A site with any other status answers as an unknown site.
• Allowed: every origin your pages are served from, one per line, exactly as the browser sends it, for example https://www.example.com. https://www.example.com and https://example.com are two origins, and an entry containing * never matches. An empty list refuses every browser request that carries an Origin, and the Sites list marks the site denies all.

Write down the site id. It is the last part of the site screen’s address, for example /delivery/sites/site_example. Your pages and your servers send it in the x-edgekit-site-id header.

See Sites and Site settings.

3. Deploy

What you save in the console is the draft. Requests read your newest deployment, so a site change reaches requests only after a deploy. In Delivery › Deployments › Versions, select Stage the draft, read the preview, then select Deploy #2 (the button names the preview’s version). See Stage and deploy a change.

EdgeKit makes your organization’s first deploy when it opens your account, so your first site already resolves. A request for a site that is not active or not in your newest deployment answers 404 not_found with the message Unknown site.. To check that the site resolves:

curl -i https://your-tenant-host/v1/id/config \
  -H 'x-edgekit-site-id: site_example'

const response = await fetch('https://your-tenant-host/v1/id/config', {
  headers: { 'x-edgekit-site-id': 'site_example' },
});

console.log(response.status); // 200 when the site is active and deployed

This request needs no credential and does not check your allowed origins.

4. Mount EdgeKit on your site’s own domain

EdgeKit’s browser code calls your site’s own origin under /edgekit/: the client API under /edgekit/v1/, and analytics events at /edgekit/a/t. Requests through your own domain always carry the user’s sign-in session, and because they are same-origin, a Content Security Policy with connect-src 'self' already allows them.

Set up the mount in one of two ways:

• Forward from what serves your site, such as your CDN, load balancer or reverse proxy:

  • /edgekit/v1/* to https://your-tenant-host/edgekit/v1/*, with the path unchanged.
  • /edgekit/a/* to https://your-tenant-host/a/*, with /edgekit removed from the path. The other analytics paths are listed on the path mount page.

  Pass the Cookie, Set-Cookie, Origin, Sec-Fetch-* and x-edgekit-site-id headers through unchanged. Without the cookies no user is ever signed in, and the allowed origins are checked against Origin. See Mount /edgekit/ on your domain.

• Run the site proxy in front of your site. It forwards /edgekit/* on your domain to your tenant host, adds EdgeKit’s script to your HTML pages and asks for your paywall feature on the server. When the outcome does not allow the page, it removes the gated part if it can find it, and covers the page if it cannot. It changes only GET requests answered 200 with HTML, and passes everything else through unchanged. See Run the site proxy.

  The proxy alone loses analytics events. It forwards /edgekit/a/t with the /edgekit prefix, and your tenant host answers analytics only at /a/t, so the event gets 200 and is dropped. Add your own /edgekit/a/* rule in front of the proxy that removes the prefix, as in the first option, or send events to your tenant host directly. See Run the site proxy.

If you can do neither, your pages can call your tenant host directly. Those requests carry a session only when the user signed in through the tenant host and it shares your site’s domain, or your organization’s cookie domain covers both hosts. Without one, decide still answers 200, as for an anonymous device. See Call the tenant host directly, and First-party mount and site proxy for the three setups side by side.

Check the mount with the same request on your own domain. It answers the same as your tenant host:

curl -i https://www.example.com/edgekit/v1/id/config \
  -H 'x-edgekit-site-id: site_example'

Verify the mount lists what each wrong answer means.

5. Issue an API key, if a server calls EdgeKit

Skip this step if only browsers call EdgeKit: the browser client holds no credential, and the allowed origins admit it. A server needs a key, for example to decide on the server or to name the user it decides for.

1. Open your site from Delivery › Delivery › Sites and go to API keys.
2. Enter a Name that says what holds the key. It is the only way to tell two keys apart later.
3. Optionally, enter Expires in (days), a whole number from 1 to 3650. Leave it empty for a key that does not expire.
4. Select Issue key, copy the key into your secret store, then select I have it.

The key is shown once. EdgeKit stores only a hash of it, so a lost key is replaced, never recovered. A new key works at once, with no deploy.

Send the key as Authorization: Bearer <key> or in the x-api-key header, together with x-edgekit-site-id naming the same site. The key is pinned to that one site: sent with another site’s id it gets 403 forbidden, and a revoked or expired key gets 401 unauthorized. Keep it on your server and never put it in a page. @edgekitcloud/client-server is the server client that sends it for you. See Issue and revoke API keys.

6. Set up each EdgeKit product

Your site is now ready for EdgeKit products. Where each one starts:

• EdgeKit Paywall: author a feature in Revenue › Decision Engine › Features and deploy it. Your page asks for it with the browser client’s decide (createClient), or your server asks the decide API.
• EdgeKit Subscriptions: set up what you sell in the Revenue › Catalog › Products and Revenue › Catalog › Offers screens. Your page sells it with the browser client’s checkout.
• EdgeKit ID: your page signs users in with the browser client’s id methods. Sign-in emails go out from EdgeKit’s own address until you set the transactional mail settings on your site’s screen in Delivery › Delivery › Sites. Those settings apply to every site in your organization, and take effect at once, with no deploy.
• EdgeKit Profile: define profile fields in Identity › Audience › Profile and deploy. Paywall rules read each one as profile.<name>.
• EdgeKit Analytics: the tracker, @edgekitcloud/analytics-browser, sends events to /edgekit/a/t by default. The event schemas it may send are in Analytics › Configuration › Schemas.
• EdgeKit Newsletters: set up lists in Messaging › Configuration › Lists. Your page reads and changes a user’s lists with the browser client’s newsletters.

Questions about these steps are answered in the getting started FAQ.