# Domain ownership: verify your domain

> How MetricRaven decides which account owns a domain: automatic page check, DNS TXT record or managed proxy, and what happens to unverified copies.

Source: https://metricraven.com/docs/domain-ownership  
Markdown: https://metricraven.com/docs/domain-ownership.md  
Section: Get started

A domain belongs to the account that proves it controls the website. Adding a domain to a site doesn't make it yours; verifying it does. Most sites are verified automatically, without you doing anything.

## How verification works

A site verifies a domain in one of three ways. The first that works counts.

| Method | How |
| --- | --- |
| Page check (automatic) | When your site starts receiving visits from a domain nobody has verified yet, MetricRaven loads `https://your-domain/` in the background and looks for your site ID (`ana_pub_…`) in the HTML. The install script carries it as `data-website-id`, so a normal install verifies itself within minutes. Installed through **Google Tag Manager**? When the page loads a GTM container (the official GTM snippet), we also read that container's public file at `googletagmanager.com` and look for your site ID there, so a GTM install verifies itself too. If it isn't found, we try again at most every 6 hours while visits keep arriving (every 10 minutes during a free trial). |
| DNS TXT record | For installs the page check can't see: other tag managers, server-side GTM, or a home page that blocks our checker. Add a TXT record named `_metricraven.your-domain` with the value shown in **Settings → General → Site → Verify** (it looks like `metricraven-site-verification=…`), then choose **Check now**. |
| Managed proxy | An active [managed proxy](https://metricraven.com/docs/managed-proxy) on a subdomain of the domain counts as proof: its CNAME can only be added by whoever controls the domain's DNS. |

**Settings → General → Site** shows each domain as **Verified** (with the method), **Not verified** or **Locked**. Admins and the owner can open **Verify** on a domain that isn't verified to see the TXT record and run a check right away. Checks are limited to a few per website every 10 minutes.

1. **Install the script on your home page**

   Follow [Install & verify](https://metricraven.com/docs/install). Once a visit arrives, the page check runs on its own.

2. **Another tag manager, or the check can't reach your page? Add the TXT record**

   Open **Settings → General → Site**, choose **Verify** next to the domain, copy the name and value into a TXT record at your DNS provider and choose **Check now**. DNS changes can take a few minutes to show.

## What the page check fetches

- Only `https://your-domain/` (or `https://www.your-domain/` when the bare domain doesn't answer), on port 443, with the user agent `MetricRavenVerifier/1.0`.
- At most 3 redirects, and only within the domain and its `www.` variant. At most 1 MB is read, with a 5-second timeout. No cookies or credentials are sent.
- Addresses that aren't on the public internet (private networks, loopback, link-local) are never fetched.
- When the page loads Google Tag Manager, up to 3 of its containers from `https://www.googletagmanager.com/gtm.js?id=GTM-…` (at most 3 MB, 8-second timeout). Only container IDs in the official GTM snippet or loader URL count, not one merely written in the page's text.

If your firewall or bot protection blocks unknown agents, allow `MetricRavenVerifier` or use the DNS record instead.

## Adding a domain someone else has

You can add any domain that no other account has verified, from the home page, **Add a site**, **Settings → General → Site**, the API, MCP or CLI. Several accounts can list the same domain while nobody has verified it. A domain another account **verified** can't be added: the answer is `409 domain_taken` ("verified by another MetricRaven account"). If you work on that website, ask its owner to invite you (**Settings → Team**), or add the site with its secret key under **Add an existing site**. MetricRaven never tells you which account verified it.

Domains are compared without `www.`, case or port. Subdomains follow one rule: **the most specific verified domain wins its hosts**.

- Verifying `example.com` covers its subdomains: another account can't add `app.example.com` (`409 domain_taken`, naming `example.com`), and sites that already list one are locked like copies of the domain itself.
- A subdomain verified on its own stays with whoever verified it, even if another account later verifies the parent. That account can still add deeper subdomains such as `api.app.example.com`.
- Listing a parent of someone else's verified subdomain is allowed (you may own `example.com` while an agency verified `app.example.com`), but that site doesn't collect from the verified subdomain or below it: those events get `403 domain_locked`. **Settings → General → Site** lists such subdomains under the domain, without saying who verified them. Everything else under the domain is collected as usual.

## During the free trial

A free trial records visits, events, payments and crawler requests only from **verified** domains (local development on `localhost` and native apps excepted). Visits from a domain that isn't verified yet are answered with `403 domain_unverified` and start a verification check, repeated every 10 minutes while they keep arriving, so recording usually starts within minutes of installing. The install check and **Settings → General → Site** show when visits are waiting for verification. Each domain gets one free trial: a domain another account already verified needs a plan.

## When another account verifies your domain

If your site lists a domain that another account then verifies, your site's copy is **locked**:

- Events from that domain are refused for your site (`403 domain_locked`). Its other domains keep collecting.
- The dashboard shows a banner with the date, and the owner and admins get one email. Neither names the other account.
- Remove the domain before that date (the banner's **Remove** button, or **Settings → General → Site**) and the site is kept with its reports. If it was the site's only domain, add the domain you do run so it keeps collecting.
- After **14 days**, a site that still lists the locked domain is deleted with all its data, the same way as deleting a website yourself.

> **Note:** Sites in the same account (the same billing owner) are never locked against each other, and demo sites never verify or get locked. If the verifying site later removes the domain or is deleted, the domain is free again and the locks lift.

## Weekly re-check

Once a week, each verified domain is checked again with the method that verified it: your site ID on the home page, the TXT record, or an active managed proxy.

- One failed check changes nothing; we try again every day.
- After **14 days** of failed checks in a row, the owner and admins get one email and the dashboard shows a notice: put the script or record back, or choose **Verify again** (any of the three methods counts).
- After **21 days**, the domain is released. Your site, its domains and its data stay as they are and nothing is locked or deleted, but another account can then verify the domain.
- Any successful check ends the streak.

## Your domain was verified by someone else

If another account verified your domain and you control the website, choose **Verify again** on the banner (or on the Locked domain in **Settings → General → Site**). We check your site's proof and the current owner's proof at that moment:

| Result | What happens |
| --- | --- |
| Yours passes, theirs fails | The domain moves to your site: your lock lifts, and the other account's copy is locked with the usual 14 days, banner and email. |
| Both pass | The domain stays where it is (for example an agency's and a client's script on the same page). Ask that site's owner to invite you. |
| Yours fails | Nothing changes. Put the install snippet on your home page, or add the TXT record, then try again. |

A domain that just changed hands can't be disputed back for 24 hours. Checks share the limit of **Check now**. Still stuck? Email [support@metricraven.com](mailto:support@metricraven.com).

## API

| Endpoint | What it does |
| --- | --- |
| GET /api/v1/site/domains?site=SITE_ID | Each domain's state: verified (method, verifiedAt, and failingSince / releaseAfter while re-checks fail), verified_other_site, locked (with deleteAfter) or unverified. Admins and the owner also get the TXT value. |
| POST /api/v1/site/domains/verify?site=SITE_ID | Check now and Verify again, body { "domain": "example.com" }. result verified, verified_other_site or not_found; on a domain another account verified it is a dispute: transferred, both_verified or not_found, and 409 dispute_cooldown (with retryAfter) within 24 hours of a transfer. 429 rate_limited after 6 checks per website (20 per user) in 10 minutes. |
| POST /api/v1/site/domains/remove?site=SITE_ID | Removes one domain, body { "domain": "example.com" }. Unlike PUT /api/v1/site it may remove the last domain, which resolves a lock. |

These use a dashboard session or an account token (admins and the owner for changes), not the site secret key. See the [site API](https://metricraven.com/docs/site-api) for the rest of the settings.
