Google Authenticating to the Admin Settings API service

Authenticating to the Admin Settings API service

The Admin Settings API feeds are private. Unauthenticated requests are not accepted. Before retrieving or updating domain properties, your client must authenticate using either the ClientLogin authentication system or OAuth.

If your client is a standalone single-user "installed" client (such as a desktop application), then you should use the ClientLogin Interface system; if your client is a multi-user web application client, then you should use 3-legged OAuth. Both of these methods involve interacting with an authentication service. The authentication service returns an authentication token that your client can then send to the Admin Settings API service along with every subsequent request on behalf of that user.

Note: For clients using ClientLogin and have been enrolled in two-step verification, use your two-step verification access code for the Passwd query parameter.

Most of the samples in subsequent sections of this document assume you are providing the appropriate authentication.

ClientLogin user name and password authentication

To use this system, you submit the email address and password of the domain administrator making the request. The authentication service returns an authentication token that your client can then send to the Admin Settings API service along with every subsequent request.

To request an authentication token using the ClientLogin mechanism, send a POST request to the following URL:

https://www.google.com/accounts/ClientLogin

The POST request contains the following Content-type header:

Content-type: application/x-www-form-urlencoded

The POST body contains a set of query parameters that look like parameters passed by an HTML form. These are:

accountType

The type of account to be authenticated. To support Google Apps users, use the HOSTED_OR_GOOGLE account type. This type is authenticated first as a hosted account. If this attempt fails, the administrator is authenticated as a Google account. This allows for the primary and secondary administrators to log in to this account.

Email

The administrator's email address

Passwd

The administrator's password, or your access code if enrolled in two-step verification. If using XML outside of a client library, the email address and password value must be URL-encoded. For example, the URL-encoding for liz@gmail.com is liz%40gmail.com

service

The Admin Settings ClientLogin service name is apps, a Google Apps service. For other service names, see the service name list.

source

Identifies your client application for support purposes. This string should take the form of your companyName-applicationName-versionID.

This example shows a POST body containing the following string with each parameter's name-value pair:

&Email=yourAdminEmail&Passwd=yourAdminPassword-or-yourAccessCode&accountType=HOSTED_OR_GOOGLE&service=apps
&source=companyName-applicationName-versionID

For more information about ClientLogin parameters, see the Authentication for Installed Applications document.

If the authentication request fails, then the server returns an HTTP 403 Forbidden status code.

If the request succeeds, then the server returns an HTTP 200 OK status code, plus three long alphanumeric codes in the body of the response: SID, LSID, and Auth. The SID is the session ID valid for the life of the session. The Auth value is the authorization token that you'll send to the Admin Settings service with each of your subsequent API requests. Google recommends keeping the authorization token in memory rather than writing it to a file. In the context of this guide, you can ignore the SID and LSID values.

Since all requests to the Admin Settings service require authentication, set the Content-type and Authorization headers in all service requests using the following format:

Content-type: application/atom+xml
Authorization: GoogleLogin auth=yourAuthToken

Where yourAuthToken is the Auth string returned from the ClientLogin POST request. Use this token for all requests in a given session. A new token is not required for each Admin Settings API request.

Note: Tokens are valid for 24 hours. If an authenticated request fails, it may mean you need to acquire another token by posting the administrator's credentials to the ClientLogin URL again.

For more information about ClientLogin authentication, including sample requests and responses, see the Authentication for Installed Applications documentation.

If you get a CAPTCHA error with your request, the error response will return a CAPTCHA token and URL:

CaptchaToken=captchaToken
CaptchaUrl=Captcha?ctoken=captchaToken
Error=cr
Url=https://www.google.com/a/example.com/ErrorMsg?Email=adminLogin
%40yourDomainName&service=apps&id=cr&timeStmp=1222898074&secTok=theCAPTCHAtoken 

For information about handling a CAPTCHA challenge, see the CAPTCHA FAQ.

OAuth for web applications

Admin Settings API service also supports 3-legged OAuth scheme for allowing web applications to manage domain settings. The OAuth guide provides more information on how to obtain access tokens

OAuth scope parameter

https://apps-apis.google.com/a/feeds/domain/

Back to top

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 control panel's Domain settings page.

Retrieving a domain's default language

To retrieve the domain's default language, send an HTTP GET request to the default language feed URL, and include an Authorization header as described in Authenticating to the Admin Settings service:

https://apps-apis.google.com/a/feeds/domain/2.0/yourDomainName/general/defaultLanguage

This operation has no parameters in the request body.

A successful response returns an HTTP 200 OK status code, along with a standard AtomPub feed with the domain's default language element. For language encoding information, see the Google Apps Email Migration API Email Language Tags.

The response entry element returns the defaultLanguage property:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='defaultLanguage' value='yourLanguageCode'/>
</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.