---
title: "Linking permissions and auto-linking API"
description: "The Link Placements to Banners grant values and how far each reaches, what a Can View share allows since release 154, the placement-side site-edit requirement, and how the auto-linking preview and apply calls report a large site."
type: "reference"
audience: [network-manager, publisher, advertiser, admin, developer]
keywords: [link placements to banners, linked, shared linked, link on entities shared for viewing only, auto-linking API, auto=true, checkedAt, apply auto-linking to own inventory]
---

Fetch the complete documentation index at: https://epom.com/ad-server/docs/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Linking permissions and auto-linking API

Reference for [Hierarchy and linking](https://epom.com/ad-server/docs/concepts/hierarchy-and-linking.md): who may link what, and the REST
calls behind the auto-linking badge.

## Linking permissions

What either linking picker offers is the role's *Link Placements to Banners* grant, which carries
two things at once — how far it reaches, and whether anything new may be linked at all:

| Grant | Reaches | New links |
|---|---|---|
| *None* | — | the linking card is gone |
| *All* | the whole network | yes |
| *Shared* | entities shared with the user as *Is Owner* or *Can Edit* — *Can View* shares too, only while the role holds *Link on entities shared for viewing only* | yes |
| *Linked* | the whole network | no — only the links that already exist |
| *Shared linked* | the same shares as *Shared* | no — only the links that already exist |

The two *linked* values are the self-serve setup: the account sees what someone else linked and
can unlink it, but never adds a link of its own. Network-manager roles that do the linking are
set to *All* or *Shared*.

Since release 154 a *Can View* share does not carry the right to link: linking changes what the
shared entity serves, so with a *Shared* or *Shared linked* grant banners are linked onto a
site's placements, unlinked from them, or the linking of a placement or banner switched off, only
through a share that may be changed — on the banner side and on the placement side alike, the
site's share for a placement and the advertiser's share for a banner. *Link on entities shared
for viewing only* gives the older reach back; the upgrade granted it to every role whose grant
reaches through shares, so nothing changed until an administrator turned it off. Where it is off,
the **Linked Banners** and **Linked Placements** cards read *Read-only* on such entities, and a
REST call is refused with a `403` naming the missing permission — *Link on entities shared for
viewing only* or *Link Placements to Banners*
([Sharing and permission model](https://epom.com/ad-server/docs/concepts/sharing-permission-model.md#layer-3--entity-shares)).

Changing the links **from the placement side** (the placement's banner list,
`PUT /rest-api/placements/{id}/banners.do`) also needs the right to edit that placement's site —
your own, shared with you for editing, or *Inventory → Update: All*. A network-wide grant (*All*,
*Linked*) therefore reaches other customers' banners from your placements, but never another
customer's placement. The banner side does not ask for the site-edit right, but a *Shared* grant
still reaches only the sites and advertisers shared with you in a way that allows linking (see
the table above).

Reach is separate again from whether the user may *see* what those entities are called — names
come from the entity-scope view grant and the mask permissions. So a role can be allowed to link
into inventory it only ever sees as `SITE_456`, and a publisher can accept creatives from
advertisers it only ever sees as `ADVERTISER_123`
([Sharing and permission model](https://epom.com/ad-server/docs/concepts/sharing-permission-model.md)).

*Apply auto-linking to own inventory* is off by default except for roles with *Auto-linking
settings* enabled; the network turns it on for publisher roles that should be able to re-apply
auto-linking themselves.

## Auto-linking over the API

`GET /rest-api/{sites,placements,campaigns,banners}/{id}/auto-linking` previews what re-applying
would change; `POST …/auto-linking/apply` applies it. Both need the same permissions as the
page: update on the site plus *Apply auto-linking to own inventory* on the publisher side, update
on the campaign plus *Auto-linking settings* on the advertiser side.

The preview's `auto=true` is the page's background check. It never answers with an error:
without access, or wherever nothing can change (the network has no auto-linking rules, the
placement opted out, no creative of the campaign has a rule, the site has no placement open to
auto-linking), it answers `skipped: false` with zero counts. A site with more than 1,000
placements open to auto-linking answers its stored background result with `checkedAt` (epoch
milliseconds), or `skipped: true`, `pending: true` and `placementCount` while there is none or it
is out of date. Without `auto` the preview checks in full, as before, and stores the result of a
large site; applying to a large site stores zero counts.

The background check never reports an error. A check that fails, an entity deleted in another
tab or a share revoked while the page is open leaves the header empty; open the page again to
retry. On a large site, links added or removed by hand in the linking trees reach the stored
result with the nightly check; saving the site or a placement, or changing an auto-linking rule,
refreshes it within about 15 minutes.

## Related

- [Hierarchy and linking](https://epom.com/ad-server/docs/concepts/hierarchy-and-linking.md)
- [Sharing and permission model](https://epom.com/ad-server/docs/concepts/sharing-permission-model.md)
- [Share sites and advertisers](https://epom.com/ad-server/docs/guides/collaboration/shares.md)
- [Users and roles](https://epom.com/ad-server/docs/guides/admin/users-and-roles.md)