Gift links

A gift link lets a user share one page with someone else. It is a signed token in the shared URL’s _gt parameter, bound to one site, one page and an expiry. It is not a grant: the person who opens it is usually anonymous, and your own rules decide what the link opens and how often.

What your organization needs

Three gift link settings decide how links are made. They apply to your whole organization and are part of your deployment:

• the create feature: the feature decide asks whether this user may create a link for this page;
• the key fact: the page fact a link is bound to, such as the article’s id;
• the lifetime: how long a link stays valid, 7 days by default.

The console has no screen for these settings, so ask EdgeKit to set them. Until the first two are set, creating a link answers 404 not_found, Gift links are not configured for this tenant.

Create a link

From a page, for the signed-in user. The browser client’s createGiftLink sends the same request:

const response = await fetch('/edgekit/v1/gift-links', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'content-type': 'application/json',
    'x-edgekit-site-id': 'site_example',
  },
  body: JSON.stringify({ context: { article_id: 'a-1' } }),
});

const { status, token } = await response.json();

if (status === 'created' && token) {
  shareUrl.searchParams.set('_gt', token);
}

From your server, with an API key. userId is who gives the link. Without it, the link is your organization’s own, with source internal:

curl -X POST https://your-tenant-host/v1/gift-links \
  -H 'authorization: Bearer YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -H 'x-edgekit-site-id: site_example' \
  -d '{"userId":"0199a4c2-7b1e-7c3d-9a4f-2e8b5d6c1a90","context":{"article_id":"a-1"},"expiresInDays":2}'

The body carries the page’s facts in context, as on decide. expiresInDays makes the link expire sooner than your organization’s gift link lifetime, 7 days by default, never later. Only the server route takes userId and expiresInDays; the browser route refuses either with 403 forbidden.

What create does

1. It decides the create feature for the user and this page. When the page has a value for the key fact, that decision counts on its meters, which is how you cap how many links a user may create. Without one, nothing is counted.
2. If the outcome’s type is not allow, it answers 200 with status denied and the decision.
3. If the page has no value for the key fact, it answers 422 unprocessable_entity, This page carries no <key fact>. The value must be a string that is not empty, or a number, of at most 512 bytes and with no |.
4. It records the link and answers 200 with status created, the token, expiresAt and the decision.

Create is not idempotent: every call counts on the create feature’s meters and makes a new link. Retry only a request that got no answer. If recording the link fails after the meters counted, the answer is 422 and the user gets no link for that count. Asking for the create feature in an ordinary decide request tells your page whether to offer a gift button, without counting anything.

Each refusal and its message is listed in Creating a gift link is refused.

Open a link

Add the token to the shared URL as ?_gt=<token>. The browser client sends the page URL’s _gt with every decide request. From your server, pass your incoming request’s _gt as giftLink. See Ask for a decision.

Decide verifies the token on its own, with no lookup. A token for another site, an expired one, a forged one or one that is too long is no gift: the decision is still 200, with gift_link.valid false.

What a rule reads

Fact	Says
gift_link.present	The request carried a gift link token, valid or not
gift_link.valid	The token verified for this site and has not expired
gift_link.id	The link’s id
gift_link.source	user for a link a user gave, internal for your organization’s own
gift_link.covers_content	The link is valid and bound to this page’s key fact value

A rule that opens the page for a gift is usually placed before the meter rules in the canvases for anonymous devices and for signed-in users without access. For example: gift_link.covers_content is true, and a gift_link meter gift-opens is under 10 in the last 30 days with +1 if this rule wins, returning an outcome with reason gift.

A gift_link meter has one count per link, whoever opens it, so it caps how often one link opens. It counts even for a user who holds a grant. A request with no valid gift link is never counted on it. See Set up a meter.

Limits

• A link opens until it expires. There is no way to withdraw one sooner.
• A link opens on the site it was made on, and no other.
• A key fact in context.* is not verified. A user who edits the request can present a link on another page that sends the same key value. Your rules still decide whether that page opens.
• Creating links has the same rate limits as decide. See Limits.