Google Apps Admin Settings API

The Google Apps Admin Settings API allows administrators of Google Apps domains to retrieve and change the settings of their domains in the form of Google Data API feeds.

These domain settings include many of the features available in the Google Apps Admin console. Example uses of this API include creating a custom control panel or integrating Google Apps domains into an existing legacy environment.

The Admin Settings API implements the Google Data API protocol. The Google Data API conforms to the Atom Publishing Protocol (AtomPub) publishing and editing model. The AtomPub HTTP requests use the Representational Set Transfer (RESTful) design approach to web services. For more information, see the Google Data Developer's Guide.

Audience

This document is intended for developers who want to write client applications that can modify and retrieve information about Google Apps domains. It provides examples of the basic Admin Settings API interactions using raw XML and HTTP.

This document assumes that you understand the general ideas behind the Google Data API protocol, and that you are familiar with the Google Apps Admin console. For more information about the Admin console, see Use your Admin console.

Getting Started

Creating an account

The Google Apps Admin Settings API is enabled for the Google Apps for Work, Education and ISP accounts. Sign up for a Google Apps for Work or Education account for testing purposes. Contact sales for an ISP account. The Admin Settings service uses Google Accounts, so if you already have an account on a domain with one of these product versions, you're all set.

This feed allows you to modify a domain's secondary contact address. In addition, use this feed to retrieve information about the domain ownership status, product version, creation date, and country code.

SAML-based Single Sign-On (SSO) allows users to use the same login and password for both Google Apps hosted services as well as other services you may be hosting within your organization. Specifically when using SSO, a hosted web application, such as Google Apps, redirects users to your organization's identity provider to authenticate users when they log in. For detailed information, see Understanding SAML-based SSO for Google Apps.

Configuring SSO involves entering the necessary information for the Google Apps service to communicate with the identity provider that stores your users' login information, as well as setting up the links users should be sent to for logging in, logging out, and for changing their passwords. The Admin Settings API allows you to update and retrieve these settings programmatically. Google uses your generated public key to verify this SSO request with your identity provider and that the private key SAML response was not modified during the network transmission.

For a short API specific summary of using the SSO settings, get your public key certificate from your identity provider, register the public key with Google, and set up your SAML-based SSO query settings. For error messages, see Troubleshooting SSO:

Sample of an Admin Settings API XML request and response

This document provides code examples of basic Admin Settings API requests and responses using raw XML and HTTP. This domain default language example shows the full XML and HTTP syntax for a request and response entry's body which is common to each operation:

To change the domain's default language, send an HTTP PUT to the default language's feed URL:

Except for the operation-specific properties and values, the atom:property elements represents a single key-value pair containing information about a property that you wish to retrieve or update. These are common to all Admin Settings API request bodies.

The domain default language response entry element returns the defaultLanguage property along with the XML syntax common to all Admin Settings API response bodies:

Managing general domain settings

The general domain API operations include managing a domain's language, organization name, maximum number of users, and the current number of users. The language and organization name settings are also editable on the Admin console's Company Profile page.

If your request fails for some reason, a different status code is returned. For more information about the Google Data API status codes, see HTTP status codes.

Updating a domain's default language

To update a domain's default language, first retrieve the entry you want to update using the Retrieving a domain's default language, modify it, and then send a PUT request, with the updated entry in the request's body, to the default language feed URL. Be sure the <id> value in your updated entry exactly matches the <id> of the existing entry.

If your request fails for some reason, a different status code is returned. For more information about the Google Data API status codes, see HTTP status codes.

Note: If the organization name has not been customized, the default is your domain name. The organization name is the full name of the account such as a company name or a university.

Updating an organization name

To update a domain's organization name, first retrieve the entry the organization's name using the Retrieving the organization name, modify it, and then send a PUT request to the organization name feed URL. Be sure the <id> value in your updated entry exactly matches the <id> of the existing entry.

When changing the domain's organization name, send an HTTP PUT to the organization name feed URL:

If your request fails for some reason, a different status code is returned. For more information about the Google Data API status codes, see HTTP status codes.

Managing account settings

The following sections demonstrate the XML format used for each account setting.

Retrieving the domain's support PIN (deprecated)

Warning: The support PIN method is deprecated. Customers are no longer required to provide a separate support PIN. This method now returns a value of obsolete.

Original documentation:

To retrieve a domain's support PIN, send an HTTP `GET` to the account information verification feed URL, and include an `Authorization` header as described in [Authenticating to the Admin Settings service](/admin-sdk/admin-settings/auth.html):

If your request fails for some reason, a different status code is returned. For more information about the Google Data API status codes, see [HTTP status codes](http://www.wikipedia.org/wiki/List_of_HTTP_status_codes).

If your request fails for some reason, a different status code is returned. For more information about the Google Data API status codes, see HTTP status codes.

Retrieving the domain administrator's secondary email address

To retrieve the domain administrator's secondary email address, send an HTTP GET to the account information administrator secondary email address feed URL, and include an Authorization header as described in Authenticating to the Admin Settings service:

A successful response returns an HTTP 200 status code, along with an AtomPub entry element. If your request fails for some reason, a different status code is returned. For more information about the Google Data API status codes, see HTTP status codes.

Note: The image file type can be in JPEG, PNG, or a GIF format. The recommended size is 143 x 59 pixels and the file should be smaller than 20Kb. When using custom logos, remember to stay within the Google Terms of Service. Refrain from using the Google logo, Gmail logo, or any other Google logos. For more information, see Logo and landing page policies.

A successful response returns an HTTP 200 OK status code, along with an AtomPub entry element. If your request fails for some reason, a different status code is returned. For more information about the Google Data API status codes, see HTTP status codes.

Managing verification settings

The following sections demonstrate the XML format used to confirm your MX record verification settings.

Note: To verify, modify, or retrieve the verification status of a domain, use the Google Site Verification API. If you did not purchase your domain through Google, you must confirm you own this domain before your services are activated. For more information, see Verifying domain ownership.

To use the Google Apps Gmail service, the account's MX records must be modified to point to Google's email servers. Without this step, the account does not receive mail. The MX record operation confirms the verification status and tests your manual MX record edits. For more information about how to edit your MX records, see Configuring MX records.

Note: Only administrators with login access to your domain hosting site can edit your MX records.

Retrieving the MX record verification status

To find out if your MX records have been updated, retrieve the domain's MX record verification status. Send an HTTP GET to the MX record status feed URL, and include an Authorization header as described in Authenticating to the Admin Settings service:

A successful response returns an HTTP 200 OK status code, along with an AtomPub feed with the domain's MX record information.

Note: The default verification status is false which means either the Google system has not recently checked your MX record configuration or your MX records have not been configured to point to the Google systems.

The GET response returns the verified and verificationMethod properties:

Use this operation to test your MX record edit and to reset the Google status of your MX record configuration.

This PUT request sets the verified property's value to true. If your MX record is correct, this MX verification PUT request returns property name='verified' value='true'. If the return value is false, it can mean your MX record updates have not been propagated, there is a typo in the MX record edit, or the MX record has not been configured. We recommend to wait the amount of time defined by the MX record's Time To Live value (TTL) and try again.

The PUT response returns the verified and verificationMethod properties:

Managing Single Sign-On settings

The Google Apps Single Sign-On feature (SSO) lets users log on to multiple services while only having to enter a login and password once. This password is stored by the domain's identity provider, not by Google Apps. For more information, see the Help Center's SSO page. The following sections demonstrate the XML format used for Single Sign-On settings.

The address that users will be sent to when they log out of the web application.

changePasswordUri

The address that users will be sent to when they want to change their SSO password for the web application.

enableSSO

Enables SAML-based SSO for this domain. If you have previously configured SSO settings, and you have subsequently set enableSSO to enableSSO=false, the settings you have previosly entered are still saved.

ssoWhitelist

A ssoWhitelist is a network mask IP address in Classless Inter-Domain Routing (CIDR) format. The ssoWhitelist determines which users log in using SSO and which users log in using the Google Apps account authentication page. If no masks are specified, all users will log in using SSO. For more information, see How do network masks work.

useDomainSpecificIssuer

A domain specific issuer can be used in the SAML request to the identity provider. Though not necessary for most SSO deployments, this feature is useful in large companies using a single identity provider to authenticate an entire organization with multiple subdomains. Giving the specific domain issuer determines which subdomain to associate with the request. For more information, see How does the Issuer element in the SAML request work?

If your request fails for some reason, a different status code is returned. For more information about the Google Data API status codes, see HTTP status codes.

This destination is the hostname or IP address of the SMTP-In mail server where the email is being routed. The hostname or IP address must resolve for Google. For more details on resolving mail host names, see Pilot Google Apps with email routing.

routeRewriteTo

If true, the message's SMTP envelope's to: field is changed to the destination hostname (user@destination's hostname), and the message is delivered to this user address on the destination mail server. If false, the email is delivered to the original message's to: email address (user@original hostname) on the destination mail server. This is similar to the Admin console's 'Change SMTP envelope' setting. For more information, see Domain settings for email routing.

routeEnabled

If true, the email routing functionality is enabled. If false, the functionality is disabled.

bounceNotifications

If true, Google Apps is enabled to send bounce notifications to the sender when a delivery fails.

accountHandling

This setting determines how different types of users in the domain are affected by email routing:
* allAccounts -- Deliver all email to this destination.
* provisionedAccounts -- Deliver mail to this destination if the user exists in Google Apps.
* unknownAccounts -- Deliver mail to this destination if the user does not exist in Google Apps.
This is similar to the Admin console's 'Delivery email for' setting. For more information about prerequisites and how to use mail routing, see Domain settings for email routing.

Note: Email routing is currently available for Google Apps for Work, Education, and ISPs accounts only.