Google Apps Admin Audit API (Deprecated)

Notice
The Google Apps Admin Audit API has been officially deprecated as of May 15, 2013. It has been replaced by the Admin SDK’s Reports API. The Google Apps Admin Audit API will continue to work until November 15, 2013.

Using the Google Apps Admin Audit API

The Admin Audit API's survey operations show your account's administrator activities in the control panel. This API's functionality along with the Email Audit API's features are key building blocks for your account's IT infrastructure. This document describes how the Google Apps Admin Audit API allows a Google Apps administrator to survey various control panel changes performed by all of your account's administrators.

This API can be used only for lawful purposes in accordance with your Customer Agreement. And, this API applies to Google Apps for Business, Education, and ISP accounts.

The Admin Audit API conforms to the Representational State Transfer (RESTful) design approach to web services.

Contents

Setting Up

Audience

This document is intended for programmers who want to write client applications that, for lawful auditing purposes, can audit a Google Apps account's administrative activities.

This document assumes that you have read the Getting Started Guide and have:

  • Gotten either a the Google Apps for Business, Education or ISP account. Sign up for a Google Apps for Business 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.
  • Become familiar with your Google Apps control panel found at http://www.google.com/a/cpanel/your domain name. For more information about the control panel, see Your Control Panel.
  • Enabled the Provisioning API from the Google Apps control panel to be able to make any calls to the Admin Audit API. To enable the API, log in to your admin account, and select the Domain settings tab. Select the User settings subtab, and then select the checkbox to enable the Provisioning API. Save your changes.
  • And, if using OAuth v1, you have gotten a Developer Console API key

Paging through API response data

Depending on the size of your account's changes and the value of your request's maxResults parameter, the API "paginates" or breaks the response into pages until all of the events are returned. Each page holds the number of entries listed in the maxResults parameter. And, if there is more than one entry, the list is ordered by time. The API response will contain a tag for which the rel attribute has a value of next. The URL identified in that tag points to the next page of results for the request. For example, if you requested all changes for your account and the total was 10 events, when the maxResults parameter is set to 5, the feed returns two pages of results, each holding five events:

GET https://www.googleapis.com/apps/reporting/audit/v1/C03az79cb/
207535951991?key=YOUR-DEV-CONSOLE-KEY&endTime=2010-11-09T23:20:50.52Z&maxResults=5

If an API response contains a next page of results, it will contain a <link> tag with a rel attribute value of next and a continuation token with the customerId. These are used to identify pagination links for the next page of entries in a feed. To avoid pagination problems, we recommend that you use this link to enable users to link to different pages of API results.

If you write your own code to process API responses, you will need to ensure that your code calls for additional pages of results as necessary.

Activity report request parameters and response properties

The Admin Audit API makes report requests and returns reports for an administrator's activities based on these request parameters and response properties.

Note: The API does not accept multiple values of a request parameter. If a particular request parameter is supplied more than once in the API request, the API only accepts the last value of that request parameter.
In addition, if an invalid request parameter is supplied in the API request, the API ignores that request parameter and returns the response corresponding to the remaining valid request parameters.

actorEmail
The person or entity making the change to the account, or causes a change to happen. The API response returns the actorEmail's IP address in the ipAddress property. Only administrators associated with the account can be an author. This includes delegated administrators.
applicationId
The applicationId determines which application activities are summarized in the the API reports. For this version of the API, the reports are for the control panel. The control panel's applicationId is 207535951991.
callerType
The callerType response property holds the type of author who performed the activity listed in the report. In this verson of the API, the callerType is a user.
  • USER - The user who performed the action listed in the report.
continuationToken
The response's continuationToken is used when a response contains a next page of results, it will contain a link tag with a rel attribute value of next and a continuation token and the customerId. Also see, Paging through API response data.
endTime
The endTime parameter sets the end of the range of time shown in the report. This is an optional request parameter. The default value is the approximate time of the API call. If the endTime is not specified, the report returns all activities from either the approximate time of the API call till startTime or the last 180 days, whichever is more recent. Note that startTime must be earlier than endTime. The endTime is in Coordinated Universal Time (UTC) format. This is RFC 3339. Convert all dates to the Coordinated Universal Time format before using them with the Admin Audit API. See an example UTC converter.
eventName
The eventName parameter is the specific name of the activity reported by the API. And each eventName is related to a specific Google Apps service or feature which the API organizes into types of events. For example, the Calendar Settings eventType structure has all of the Calendar eventNames reported by the API. When an administrator changes a Calendar setting, the API reports this activity in the eventType and eventName parameters. The eventName list below is organized by the event types.

For eventName request parameters in general:

  • If no eventName is given, the service returns all possible instances of an eventName.
  • When you request an eventName, the API's response returns all activities which contain that eventName. It is possible that the returned activities will have other eventNames in addition to the one requested.

The eventNames in the following list link to the Event Name Reference for more details.

Google Calendar event names

Chat event names

Delegated Admin event names

Google Docs event name

Domain event names

Gmail Event Names

Google Groups Event Names

Mobile Event Names

Organization Event Names

Google Sites Event Names

User Event Names

eventType
The Google Apps service or feature that an administrator changes is identified in the eventType attribute which identifies an event using the eventName attribute. An eventType property is returned in the response body. It is not used in the request body. The eventTypes are:
  • CALENDAR_SETTINGS
  • CHAT_SETTINGS
  • DELEGATED_ADMIN_SETTINGS
  • DOCS_SETTINGS
  • DOMAIN_SETTINGS
  • EMAIL_SETTINGS
  • GROUP_SETTINGS
  • MOBILE_SETTINGS
  • ORG_SETTINGS
  • SITES_SETTINGS
  • USER_SETTINGS
maxResults
The maxResults determines how many activity records are shown on each response page. For example, if the request sets the maxResults=1 and the report has two activities, the report has two pages. The first page has a pagination URL to the second page. The maxResults parameter is optional in the request. The maximum maxResults is 1000 and this is the default value as well.
startTime
The startTime parameter sets the beginning of the range of time shown in the report. The report returns all activities from startTime till endTime (see below). The startTime is in Coordinated Universal Time (UTC) format. RFC 3339. Convert all dates to the Coordinated Universal Time format before using them with the Admin Audit API. See an example UTC converter.
time
The response's time property shows when the event occurred. This is in the UTC format.

Accessing Administrator Activity Information

Managing administrator activity reports

Following the RESTful design criteria, the API returns administrator activity reports for specific types of control panel changes using HTTP GET requests. Each report uses the basic report endpoint request with report specific parameters such as an administrator's name or a specific control panel change which is called an event name.The maximum time period for each report is the last 180 days. These activity reports include delegated administrator activities.

Retrieving a customerId

A Google Apps account is uniquely identified by a customerId. This identifier is not the same as the account's domain name nor the customer's public business or personal name. This immutable string identifies the Google Apps account and is used in any administrator activity request and response used in the API.

To retrieve a customerId for the account of the authenticated administrator making this request, send a GET request to the customer feed's URI. Include the Authorization header as described in API authentication section of this document. Also note the spelling of 'customerId' has a capital 'I':

GET https://apps-apis.google.com/a/feeds/customer/2.0/customerId

A successful response returns an HTTP 200 status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the entry elements. Initially, the customerOrgUnitName and the customerOrgUnitDescription values are the domain name. These can be edited in the control panel. This response example returns the C03az79cb customerId:

<?xml version='1.0' encoding='UTF-8">
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/ apps/2006'>
<id>https://apps-apis.google.com/a/feeds/customer/2.0/C03az79cb</id> <updated>2008-10-17T15:02:45.646Z</atom:updated> <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/customer/2.0/C03az79cb'/>     <link rel='edit' type='application/atom+xml'     href='https://apps-apis.google.com/a/feeds/customer/2.0/C03az79cb'/>     <apps:property name="customerId" value="C03az79cb" />     <apps:property name="name" value="example.com" />     <apps:property name="description" value="The customerId of the example.com account" />
    <apps:property name="customerOrgUnitName" value="example.com" />     <apps:property name="customerOrgUnitDescription" value="customer org unit for example.com account" /></entry>

The customerId parameters

customerId
The customerId is the system's unique identifier for the Google Apps customer's account. This ID is used in all request and response operations. The customerId can be called by any domain administrator for this account.

The customerId parameter's format may change in future API releases. When making an API request, both formats are supported. But future API responses may contain a different customerId in the URL's response links than the customerId value used in your request. If your client application uses the request's customerId as a key value for persistent data, this key could break if the response returns a different customerId value

name
The name helps to identify the customerId to a specific Google Apps account. Initially, this property's value may be the account's domain name. The name should be no more than 128 characters.

description
The description is the descriptive text referring to the account's domain name. This property value may be an empty string if no description has been entered, and if entered, the description should be no more than 512 characters.

Retrieving all administrative activities

To get a report of all administrative activities done for an account, use the following GET HTTP request. Include the Authorization header as described in API authentication. This includes delegated administrators:

GET https://www.googleapis.com/apps/reporting/audit/v1/the customer ID/
the application ID?endTime=a UTC formatted date&maxResults=the number of events

This example gets a report on the administrative changes for the account's customer whose ID is C03az79cb, for the control panel application (application ID 207535951991), and uses a Developer Console API key. This example returns one change event per response page. For more information about response pagination, see Paging through API response data:

GET https://www.googleapis.com/apps/reporting/audit/v1/C03az79cb/207535951991
?key=YOUR-DEV-CONSOLE-KEY&endTime=2010-10-28T05:14:18.345Z&maxResults=1

This operation has no parameters in the request body.

A successful response returns a 200  HTTP status code. Along with the status code, the response returns the administrative activity report showing all of the control panel changes for this account for the past 180 days. This example is a JSON formatted response:

JSON Response

{
 "kind": "audit#activities",
 "items":  [
  {     
   "kind": "audit#activity",
   "id":  {
     "time":"2010-10-28T02:02:45.646Z",
     "uniqQualifier":"-nnnnnnnnnnnnnnn",
      "applicationId":"207535951991",
      "customerId":"C03az79cb"
     },
     "actor": {
       "callerType":"USER",
       "email":"john@example.com"
     },
     "ownerDomain":"example.com",
     "ipAddress": "nnn.nnn.nnn.n",
     "events": [
       {
         "type":"USER_SETTINGS",
	 "name":"CHANGE_SSO_SETTINGS",
         "parameters":  [
	   {"name":"DOMAIN_NAME",
	    "value":"john@example.com"
	   },
	  ]
	 },
	 {"type":"DOMAIN_SETTINGS",
	  "name": "TOBBLE_SSO_ENABLED",
          "parameters": [
            {
	      "name":  "DOMAIN_NAME",
	      "value": "john@example.com"
            },
            {
              "name": "NEW_VALUE",
              "value": "false"
            }
          ]
        }
      ]
    }
  ],
"next": "https://www.googleapis.com/apps/reporting/audit/v1/C03zogbo9/207535951991?maxResults\u003d1&alt\u003djson&continuationToken\u003dA:nnnnnnnnnnnnnn:-nnnnnnnnnnnn:207535951991:C03zogbo9"
}

Retrieving all activities by an administrator

To get a report of all control panel activities done by a specific administrator, use the following GET HTTP request. Include the Authorization header as described in API authentication:

GET https://www.googleapis.com/apps/reporting/audit/v1/the customer ID/
the application ID?startTime=a UTC formatted date&maxResults=the number of
events
&actorEmail=the administrator's primary email address

This example gets a report on all changes to the control panel application done by john@example.com. This example returns one change event per response page. For more information about response pagination, see Paging through API response data:

GET https://www.googleapis.com/apps/reporting/audit/v1/C03az79cb/207535951991
?key=YOUR-DEV-CONSOLE-KEY&startTime=2010-10-28T05:14:18.345Z
&maxResults=1&actorEmail=john@example.com
This operation has no parameters in the request body.

A successful response returns a 200  HTTP status code. Along with the status code, the response returns an activity report showing all of the control panel changes for this domain done by the administrator, john@example.com. This example is a JSON formatted response:

JSON Response

{
 "kind": "audit#activities",
 "items":  [
  {     
   "kind": "audit#activity",
   "id":  {
     "time":"2010-10-28T02:02:45.646Z",
     "uniqQualifier":"-nnnnnnnnnnnnnnn",
      "applicationId":"207535951991",
      "customerId":"C03az79cb"
     },
     "actor": {
       "callerType":"USER",
       "email":"john@example.com"
     },
     "ownerDomain":"example.com",
     "ipAddress": "nnn.nnn.nnn.n",
     "events": [
       {
         "type":"USER_SETTINGS",
	 "name":"CHANGE_SSO_SETTINGS",
         "parameters":  [
	   {"name":"DOMAIN_NAME",
	    "value":"john@example.com"
	   },
	  }
	 },
	 {"type":"DOMAIN_SETTINGS",
	  "name": "TOBBLE_SSO_ENABLED",
          "parameters": [
            {
	      "name":  "DOMAIN_NAME",
	      "value": "john@example.com"
            },
            {
              "name": "NEW_VALUE",
              "value": "false"
            }
          ]
        }
      ]
    }
  ],
"next": "https://www.googleapis.com/apps/reporting/audit/v1/C03zogbo9/207535951991?maxResults\u003d1&alt\u003djson&continuationToken\u003dA:nnnnnnnnnnnnnn:-nnnnnnnnnnnn:207535951991:C03zogbo9"
}

Retrieving all activities by event name

To get a report of all instances of a specific change type such as adding a nickname or suspending a user, use the following GET HTTP request. Include the Authorization header as described in API authentication:

GET https://www.googleapis.com/apps/reporting/audit/v1/the customer ID/
the application ID
?startTime=a UTC formatted date&maxResults=the number of events
&eventName=the event name

This example gets a report on all control panel instances of changing a user's last name. This example returns one change event per response page. For more information about response pagination, see Paging through API response data:

GET https://www.googleapis.com/apps/reporting/audit/v1/C03az79cb/207535951991
?key=YOUR-DEV-CONSOLE-KEY&startTime=2010-10-28T05:14:18.345Z
&maxResults=1&eventName=CHANGE_LAST_NAME

This operation has no parameters in the request body.

A successful response returns a 200 HTTP status code. Along with the status code, the response returns an activity report showing all of the control panel changes of user's last name.

Note: When retrieving an eventName, the API retrieves the activities where this event occurred. For each activity, the response includes all of the activity's events including the event specified in the API request.

JSON Response

{
 "kind": "audit#activities",
 "items":  [
  {     
   "kind": "audit#activity",
   "id":  {
     "time":"2010-10-28T02:02:45.646Z",
     "uniqQualifier":"-nnnnnnnnnnnnnnn",
      "applicationId":"207535951991",
      "customerId":"C03az79cb"
     },
     "actor": {
       "callerType":"USER",
       "email":"john@example.com"
     },
     "ownerDomain":"example.com",
     "ipAddress": "nnn.nnn.nnn.n",
     "events": [
       {
         "type":"USER_SETTINGS",
	 "name":"CHANGE_SSO_SETTINGS",
         "parameters":  [
	   {"name":"DOMAIN_NAME",
	    "value":"john@example.com"
	   },
	  }
	 },
	 {"type":"DOMAIN_SETTINGS",
	  "name": "TOBBLE_SSO_ENABLED",
          "parameters": [
            {
	      "name":  "DOMAIN_NAME",
	      "value": "john@example.com"
            },
            {
              "name": "NEW_VALUE",
              "value": "false"
            }
          ]
        }
      ]
    }
  ],
"next": "https://www.googleapis.com/apps/reporting/audit/v1/C03zogbo9/207535951991?maxResults\u003d1&alt\u003djson&continuationToken\u003dA:nnnnnnnnnnnnnn:-nnnnnnnnnnnn:207535951991:C03zogbo9"
}

Retrieving all activities by event name and administrator

To get a report of all control panel changes done by a specific event name and a specific administrator, use the following GET HTTP request. Include the Authorization header as described in API authentication:

GET https://www.googleapis.com/apps/reporting/audit/v1/the customer ID/
the application ID
?startTime=a UTC formatted date&maxResults=the number of events
&eventName=the event name&actorEmail=the admin's primary email address

This example gets a report for all control panel changes to user last names that were done by john@example.com.  This example returns one change event per response page. For more information about response pagination, see Paging through API response data:

GET https://www.googleapis.com/apps/reporting/audit/v1/C03az79cb/207535951991
?key=YOUR-DEV-CONSOLE-KEY&startTime=2010-10-28T05:14:18.345Z
&maxResults=1&eventName=CHANGE_LAST_NAME&actorEmail=john@example.com

This operation has no parameters in the request body.

A successful response returns a 200 HTTP status code. Along with the status code, the response returns the administrator's activity report showing all control panel changes to user last names and were done by the administrator, john@example.com.

Note: When retrieving an eventName, the API retrieves the activities where this event occurred. For each activity, the response includes all of the activity's events including the event specified in the API request.

JSON Response

{
 "kind": "audit#activities",
 "items":  [
  {     
   "kind": "audit#activity",
   "id":  {
     "time":"2010-10-28T02:02:45.646Z",
     "uniqQualifier":"-nnnnnnnnnnnnnnn",
      "applicationId":"207535951991",
      "customerId":"C03az79cb"
     },
     "actor": {
       "callerType":"USER",
       "email":"john@example.com"
     },
     "ownerDomain":"example.com",
     "ipAddress": "nnn.nnn.nnn.n",
     "events": [
       {
         "type":"USER_SETTINGS",
	 "name":"CHANGE_SSO_SETTINGS",
         "parameters":  [
	   {"name":"DOMAIN_NAME",
	    "value":"john@example.com"
	   },
	  }
	 },
	 {"type":"DOMAIN_SETTINGS",
	  "name": "TOBBLE_SSO_ENABLED",
          "parameters": [
            {
	      "name":  "DOMAIN_NAME",
	      "value": "john@example.com"
            },
            {
              "name": "NEW_VALUE",
              "value": "false"
            }
          ]
        }
      ]
    }
  ],
"next": "https://www.googleapis.com/apps/reporting/audit/v1/C03zogbo9/207535951991?maxResults\u003d1&alt\u003djson&continuationToken\u003dA:nnnnnnnnnnnnnn:-nnnnnnnnnnnn:207535951991:C03zogbo9"
}

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.