Getting Started

Introduction

The Google Site Verification API is intended for developers who want to write applications or services that automate the process of verifying ownership of a site or domain. This is important, since some Google services can only be used by website or domain owners. You can use the Google Site Verification API to validate that the authenticated user is an owner of the domain or site, possibly as the first step in programmatically provisioning other Google services.

This document assumes that you're familiar with web programming concepts, web data formats, and that you have the ability to programmatically modify the files or DNS records of your website or domain.

Overview

You can use the Google Site Verification API to modify a user's Google site verification data. Users can only access certain Google services if their verification data shows that they are the owners of the particular website domain. You can use the API to generate verification tokens for authenticated users, which your code can place in various ways on your websites or domain records on their behalf. Once the token is in place, you make a call to the API to ask Google to check for the token. If Google finds the token, it registers the authenticated user as an owner of the website or domain. You can also use the API to modify the ownership list on the user's behalf, or to remove site ownership altogether.

All API calls need to be authorized by an authenticated user, and all API calls are executed in the context of the authenticated user's account.

As a concrete example of when you might use this API, suppose you provide a web hosting service. Your users want to be able to use Google's Search Console to get information about their site. In order for them to do this, Google needs to know that they really own it. So you provide your users with an interface that asks them to verify their ownership of the site. They give your application access to their verification data, and it can now execute code that requests a token on their behalf, places it in a file on their site structure, and asks Google to check for it. When Google finds the token, it grants ownership of the site to the user by updating their verification data. They can now use Search Console to get the information they want.

Before you start

Get a Google Account

You should make sure that you have a Google Account set up. We recommend that you use a separate Google Account for development and testing purposes to protect yourself against accidental data loss.

Get familiar with Site Verification

If you're unfamiliar with Google Site Verification API concepts, you should read this document, experiment with the verification user interface, and read the associated help documentation before starting to code.

Learn how to authorize requests

Every request your application sends to the Google Site Verification API must include an authorization token. The token also identifies your application to Google.

About authorization protocols

Your application must use OAuth 2.0 to authorize requests. No other authorization protocols are supported. If your application uses Sign In With Google, some aspects of authorization are handled for you.

Authorizing requests with OAuth 2.0

All requests to the Google Site Verification API must be authorized by an authenticated user.

The details of the authorization process, or "flow," for OAuth 2.0 vary somewhat depending on what kind of application you're writing. The following general process applies to all application types:

1. When you create your application, you register it using the Google API Console. Google then provides information you'll need later, such as a client ID and a client secret.
2. Activate the Google Site Verification API in the Google API Console. (If the API isn't listed in the API Console, then skip this step.)
3. When your application needs access to user data, it asks Google for a particular scope of access.
4. Google displays a consent screen to the user, asking them to authorize your application to request some of their data.
5. If the user approves, then Google gives your application a short-lived access token.
6. Your application requests user data, attaching the access token to the request.
7. If Google determines that your request and the token are valid, it returns the requested data.

Some flows include additional steps, such as using refresh tokens to acquire new access tokens. For detailed information about flows for various types of applications, see Google's OAuth 2.0 documentation.

Here's the OAuth 2.0 scope information for the Google Site Verification API:

To request access using OAuth 2.0, your application needs the scope information, as well as information that Google supplies when you register your application (such as the client ID and the client secret).

Tip: The Google APIs client libraries can handle some of the authorization process for you. They are available for a variety of programming languages; check the page with libraries and samples for more details.

Google Site Verification API background

Concepts

You can use the Google Site Verification API to establish a user's ownership of the following types of web resources:

• Domain: A domain or subdomain. The owner of a domain is considered to be the owner of all sites and subdomains under that domain. For example, the direct owner of bar.com is also considered to be the indirect owner of foo.bar.com.
• Site: A URL corresponding to the base domain and path of a website. The owner of a site is considered to be the owner of all sites under it. For example, the owner of “http://www.example.com/site” is also considered to be the owner of “http://www.example.com/site/subsite”.

Because domain ownership is more broadly applicable than site ownership, we recommend that you verify with domains whenever feasible.

The process of establishing ownership starts with your application requesting a “verification token” on behalf of the user. The verification token is a special string that your code must then place on their website or domain. After the token is in place, your application can make a request to the Google Site Verification API that checks for the token and records ownership when it is found.

Limitations

For security and technical reasons, Google Site Verification API enforces some restrictions on how it is used:

• Data access for authenticated user only: All operations require user authentication and authorization.
• Verification for authenticated user only: The API can only verify ownership of sites or domains for the currently authenticated account. However, the authenticated user can delegate ownership to other users after their ownership of a site has been verified. Note that all owners are notified by email whenever changes are made to the ownership list.
• Normalized URLs and domain names only. The Google Site Verification API does not support IDN (International Domain Name) encoding. Be sure to normalize all URLs, domain names, and email address domains to the standard domain name character set (RFC 1034 §3.5) using Punycoding if necessary.

Verification methods and tokens

The API provides calls for the separate phases of verification:

• Placing the verification token: There is an API call for retrieving a verification token to place on the authenticated user's site. If a user has more than one site, you must obtain a different token for each site.
• Checking for the presence of the verification token: There is a separate API call to request that Google check for the token in order to verify that the authenticated user owns a site.

There are several methods for verifying a website or domain that your application can use; the one you select depends on what works best for your requirements. Where to place the token, as well as the type of token itself, depends on which verification method you choose.

Domain verification method

There are two verification methods available for domains:

DNS_CNAME

Your application creates a new CNAME record for the owner's domain, possibly through their domain registrar, using the token for the record data. The token is composed of two parts separated by a space: the first part is the new CNAME record's name, the second part is the new CNAME record's value.

DNS_TXT

Your application creates a new TXT record for the owner's domain, possibly through their domain registrar, using the token for the record data.

See the help center documentation on the DNS verification method for more information.

Site verification methods

Three verification methods are available for sites:

File

Your application places the token, in the form of a file, on the owner's website. You must create a file, named to match the token string, with the following contents:

google-site-verification: token

For example, if a user owns the site http://www.example.com/, and the returned token is google12cfc68677988bb4.html, then you simply need to create a file at http://www.example.com/google12cfc68677988bb4.html (at the top level of their site), with these contents:

google-site-verification: google12cfc8677988bb4.html

See the help center documentation on the File verification method for more information.

Meta

Your application inserts the token, in the form of an HTML <meta> tag, within the <head> element of the default file (index.html, default.html, etc.) at the top level of the owner's site. An HTML file with a Meta verification token might look like this:

<html>
  <head>
    <title>Awesome Dive Sites</title>
    <meta name="google-site-verification" content="-dhsoFQadgDKJR7BsB6bc1j5yfqjUpg_b-1pFjr7o3x" />
  </head>
  <body>
    ...

See the help center documentation on the Meta verification method for more information.

Analytics

Your application uses an existing Google Analytics tracking code that is already on the owner's website. The tracking code must belong to their Analytics account, and the snippet must be located in the HEAD tag in order to work. See the help center documentation on the Analytics verification method for more information.

Tag Manager

Your application uses an existing Google Tag Manager container code that is already on the owner's website. The container code must belong to their Tag Manager account. See the help center documentation on the Tag Manager verification method for more information.

It can be helpful for your understanding of the core concepts and workflow if you first try verifying a few sites manually with the Site Verification user interface.

Data model

Web Resource

The Google Site Verification API applies REST semantics (HTTP GET, POST, etc.) to entities called web resources. A Web Resource is a website or a domain that belongs to the authenticated user.

Here is an example of a web resource:

{
  "owners": [
    "myself@example.com",
    "another@example.com"
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com/",
    "type": "SITE"
  }
}

The id field is a unique identifier for this web resource. You use it to reference this particular web resource for retrieval and modification. Store the id field from the output of the list operation for later use as the identifier.

The site object contains the web resource's URL or domain name, and the type of the resource. Sites are specified with the type SITE; domains are specified with the type INET_DOMAIN.

The owners array is the complete list of owners for the web resource, represented by their email addresses. By adding or removing email addresses from the owners list, the authenticated user can grant co-ownership or revoke ownership for other users. Additional owners who have placed tokens of their own on the site or domain also appear in the owners list, along with any of their co-owners.

Users who have been granted co-ownership can also grant co-ownership, as long as there is at least one verified owner with a token on the site.

Web Resource Collection

The web resource collection is a complete listing of all the web resources that belong to the authenticated user. You can verify ownership of sites or domains simply by attempting to add new web resources to the authenticated user's web resource collection. Only verified sites or domains are successfully added to their collection.

As previously stated in the Limitations section, web resources that belong to users other than the authenticated user are not accessible through the Site Verification API.