Linking permissions and auto-linking API

Reference for Hierarchy and linking: 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).

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).

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
• Sharing and permission model
• Share sites and advertisers
• Users and roles