Read the organization’s domains
GET /api/v2/accounts/{customerId}/organization-domains
customerId is the organization. An administrator of the organization can read
it, and so can Apostra staff supporting the organization.
Errors
401 UNAUTHORIZED: no signed-in person.403 ACCESS_DENIED: the caller is neither an administrator of the organization nor Apostra staff supporting it, or used an API key.404 NOT_FOUND: the account is not an active organization.
See the domains in the Domains page
In the web app, open Settings → Organization → Domains while you’re in your organization’s account, or select a domain in the Organization’s Accounts list. From one of the organization’s accounts, selecting a domain switches you to the organization first: domains are managed in the organization’s own account. In an assistant connected to your organization’s account, ask to open the Domains page, or callopen_domains_page.
The page shows the same domains as the read above: for each one, whether it is
proved and how, when it was proved, the accounts that use it, and whether it is
locked.
A domain is locked when accounts using it have advertisers. Its claim cannot
change, because changing it would change those accounts’ identity at every
seller. The page names the accounts that hold the lock.
An administrator of the organization can open the page, from any of its
accounts, and so can Apostra staff supporting the organization.
An administrator also claims, changes and proves the domain on the page. These
follow the same rules as the routes below:
- Claim or change. The page sends the domain you last saw with each change, so a change someone else made meanwhile is refused instead of overwritten. A locked domain offers no change.
- Prove with a DNS record. The page shows the TXT record to publish. Check it once it’s published; if another organization also claims the domain, the check files a staff review instead.
- Ask Apostra to review. Apostra staff review the claim and follow up by email, so this needs a signed-in person with an email address.
Claim or change the domain
PUT /api/v2/accounts/{customerId}/organization-domains/claim
A direct administrator of the organization can claim, from any of its accounts
(the web app moves you into the organization to open its settings), and so can
Apostra staff signed in to Apostra’s own account. Staff working inside your
organization through a support session, or switched into it, cannot claim for
it. An organization claims one
domain. Claiming a different domain changes the claim: the accounts
using it move with it and keep their operating-unit codes, and the new domain
starts unproved. Only one organization can verify a domain: a domain another
organization has verified cannot be claimed.
Read the organization’s domains again to see the claim’s state.
Errors
400 VALIDATION_ERROR: a missing field, or a value that is not a domain.401 UNAUTHORIZED: no signed-in person.403 ACCESS_DENIED: the caller is not a direct administrator of the organization or Apostra staff in Apostra’s own account, used a support session, or used an API key.404 NOT_FOUND: the account is not an active organization.409 CONFLICT, with areason:organisation_domain_verified_elsewhere: another organization has already verified the domain. Ask Apostra for a staff review if your organization operates as it.organisation_claim_changed: the claim changed since you read it. Read it again and retry.organisation_claim_in_use: accounts using the current claim have advertisers. Changing it would change their identity at every seller.organisation_claim_unit_taken: an account’s operating-unit code is already used under the new domain.
Prove the domain
An organization proves its claimed domain the same two ways an account proves its registered domain: a DNS TXT record, or a review by Apostra staff. Start the DNS check on the organization itself (see Verify with a DNS record); for an organization that claims a domain, the record proves the claimed domain. Proving the claim also makes it the organization’s approved registered domain. On an organization the two are one domain, so one proof covers what your accounts operate as at sellers, domain auto-join to the organization, and eligibility for single sign-on. Your accounts keep their own auto-join settings, and each takes its registered domain from the organization’s verified domains (see below). If another organization also claims the domain, or has it as its registered domain, a passing DNS check does not verify it. The check answers withreviewRequested: true and keeps the TXT record in place, and Apostra staff
decide which organization owns the domain. Until then the domain reads as
verifying. Filing the review needs a signed-in person with an email address,
so Apostra can follow up.
Pick an account’s auto-join domain
Every domain is held at the organization. An account does not type a domain of its own: its registered domain, the one that decides email auto-join, is one of the organization’s verified domains, or none.- A child buyer or agents account picks from the organization’s verified domains, or clears the domain. In the web app this is Settings → Account configuration → Auto-join domain in the child account. The picked domain takes the organization’s proof, so it needs no DNS record or review of its own.
- A domain the account already holds that the organization has not verified stays as it is, with the approval it has today, until you clear it or replace it with one of the organization’s domains. It cannot be edited to another typed domain.
- The organization’s own account has no such setting: its domain is the claim above.
- A seller account keeps its own brand domain, typed and verified as before, until the organization’s claims take it over in a later step.
- A standalone account types and verifies its own domain, as before.
- An account that converts into a child of a new organization keeps the domain it has, as a held domain.
400 VALIDATION_ERROR that points to the Domains
page. Seller accounts and Apostra staff are not restricted.
Related
Verify operator domain
Prove control of the domain
Which domain is which
Sign-in, operator and brand domains