Skip to main content
An organization claims the domain it operates as. Its accounts use that domain: a buyer account as its operator domain, with its own operating-unit code, and a seller account as its brand domain. See Which domain is which for how this differs from the domains used for sign-in. These routes need a signed-in person: the web app, or an assistant connected with your Apostra sign-in. API keys and other machine credentials are refused.

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 call open_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.
Apostra staff supporting the organization see the page without these actions.

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 a reason:
    • 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 with reviewRequested: 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.
In the Add account dialog a Buyer account takes the same picker (default none); a Seller account keeps its typed brand domain. When someone signs up to a child buyer or agents account that has no domain, the account takes their email domain only if the organization has verified it. To use a new domain, claim and prove it on the organization first, then pick it on the account. The same rule applies to updating an account’s domain and to creating an account with a domain: for a buyer or agents account, a domain the organization has not verified is refused with a 400 VALIDATION_ERROR that points to the Domains page. Seller accounts and Apostra staff are not restricted.

Verify operator domain

Prove control of the domain

Which domain is which

Sign-in, operator and brand domains