Skip to main content
An advertiser grant lets the organization that owns an advertiser give another organization reviewed access to specific advertisers. A grant names every advertiser ID and every capability, the invited organization must accept it, and it always has an expiry date. The owner keeps ownership and the existing advertiser and campaign IDs. A grant does not expose account IDs, members, billing, unrelated or future advertisers, or private advertiser configuration. A name, an email domain, a CRM association, a signup history, a provider, an external Business Manager membership or a Partner status never creates authority.

​
Who can use grants

Grants are in limited beta. An organization can use them when all of these hold:
  • it is an eligible organization (a standalone or parent account);
  • Apostra has given it an active, time-limited beta entitlement; and
  • Apostra has switched grants on for its cohort.
When an organization does not meet them, save_advertiser_grant is left out of tools/list and a call is refused with ACCESS_DENIED. Being named in a grant does not bypass these checks. Ask your Apostra contact to enroll the organization. Every grant change needs a person signed in directly as an administrator of the organization. A service token, a user API key, an advertiser-scoped credential, an impersonated session or an inherited child-account session cannot invite, accept, reject or revoke, and cannot list or read grants either. Run the call in the organization’s own account: from a child account the call is refused with “Open the Organization account before changing advertiser grants.” A buyer agent gains nothing from a grant. It reaches only the advertisers its own organization owns, so a grant does not let it list or read a delegated advertiser or its campaigns. See Buyer agents.

​
Invite an organization

Use save_advertiser_grant with action: "invite":
The inviting and invited organizations must be different. An advertiser the inviter does not own, a system advertiser, or an expiry outside the window is refused with VALIDATION_ERROR or ACCESS_DENIED. While a pending or active grant exists for the same two organizations and advertiser, reject, revoke or let it expire before you invite again; an overlapping invitation is refused with CONFLICT. The invited organization’s administrator gives you its reference. The reference also appears as grantor.organizationRef or grantee.organizationRef on every grant that organization is part of. If the other administrator cannot find it, ask through save_ask.
A grant records the reviewed campaign capabilities and the authorization boundary around them. Campaign read and manage grants do not yet extend the buyer campaign tools to the invited organization. Those tools stay scoped to the account that owns the advertiser until delegated campaign access is released.

​
Accept, reject or revoke

The invited organization accepts or rejects an invitation. Only that organization can record either answer.
Send action: "reject" to decline. The inviting organization ends a pending or active grant at once with action: "revoke" and a reason. accept, reject and revoke take only grantRef and reason; they cannot change the parties, advertisers, capabilities, expiry or purpose. A grant is invited, active, rejected, revoked or expired. Accepting, rejecting, revoking and an observed expiry each add an event to the grant’s history; earlier events are never rewritten. A revoked or expired grant stops working immediately, and a cached grant is never evidence of current authority: every delegated operation checks the active, accepted grant for the exact advertiser and capability again. Removing the beta entitlement or the cohort exposure from either organization also stops access. It does not delete the grant or its history.

​
Read grants

Call search with kind: "advertiser_grant" in a buyer or seller account. Narrow it with query or with filter.grantStatus, one or more of invited, active, expired, rejected and revoked. Each result holds grantRef, status, grantor, grantee, advertiserCount, capabilities, purposePreview and expiresAt. A page holds at most 25 grants, whatever limit you send. When more follow, the page is truncated: it returns truncated: true, totalLowerBound and a nextCursor to pass back. Only an untruncated first page returns the exact total. Call get with kind: "advertiser_grant" and id set to the grantRef for the whole grant: the exact advertisers, and the events history with each event’s type, actor, reason and observedAt. Names, purposes and reasons are customer-written text, so Apostra wraps them as untrusted output.

​
Errors

See Errors for how V3 reports them.