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.

Get Started with the Google Apps Admin Audit API

This document details the background knowledge that you need to use with the Google Apps Admin Audit API. For API usage details, see Using the API guide.

Contents

Introduction

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.

With the Google Apps Admin Audit API you can survey the activities of all of your account's administrators in the control panel. The API gives details about changes to a key subset of your Google Apps services and features settings including settings for Calendar, Chat, your delegated administrators, Docs, domain configuration, Gmail, Groups, mobile settings, organization hierarchy, Sites, and user settings. In addition to the setting changes, the API returns specifics about the change activity itself, including the IP address used by the administrator.

This API applies to Google Apps Business, Education, and ISP accounts.

Before you start

Get a Google Apps account

Sign up for a Google Apps for Business or Education account. Contact sales for an ISP account. Once the account is created, verify your domain ownership. If you already have a Google Apps account and have verified your domain ownership, then 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 Log into your control panel.

Enable your Google Apps APIs

Enable the Provisioning API from your Google Apps control panel to be able to make API 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.

Get your API key

For OAuth client applications not using OAuth 2.0, set up a new project and get an API key from the Google Developer Console:

  1. Set up a new project.
  2. Activate AUDIT API for this project
  3. See the FAQ to:

    Configure your project's Traffic control with the "Expected request source:" as "Server-side applications"

  4. This is an example of how an API key is used in a request. All requests should be identified with this API key.
    GET https://www.googleapis.com/apps/reporting/audit/v1/C03k80ujw/207535951991?endTime=2010-11-09T23:20:50.52Z&maxResults=5
    &key=YOUR_DEV_CONSOLE_KEY_HERE

To use the API, you need to set up authentication and refer to the Using the API Guide as you build your client application.

Admin Audit API background

Admin Audit concepts

The API returns a survey of administrator control panel activities. The API response categorizes these administrator changes by either a Google Apps service or feature. Each summary uses a basic report endpoint request with specific parameters for a particular change event.

  • The administrator making the change is an actor or author, and the API includes the administrator's IP address.
  • The API categorizes an account's changes by service or feature. These categories have related settings which are surveyed by the API. Specifically:
    • The API identifies which Google Apps service or feature has been modified and returns this in the response's eventType property. Examples of an eventType are the Calendar service and an account's organization hierarchy.
    • Settings are surveyed by the API for any changes and are identified by an eventName. An example of a Calendar setting is the creation of a Calendar resource, and the moving an org unit to a new parent organization is an example of an organization hierarchy setting. The API surveys a key set of the control panel settings, but not all settings.

Admin Audit API data model

The Admin Audit API operates on a report resource which represents surveys of specified administrative activities within an account. Each report is an individual data entity with a unique identifier.

Admin Audit API operations

You can invoke audit methods in the Admin Audit API, as described in the following table.

Operation Description REST HTTP mappings
list Lists all audited events within a specific time, event name or administrator. All list operations require authentication. GET on an audit URI.

Calling style

REST

The API uses the Representational State Transfer (RESTful) design approach to invoke web services by using the GET HTTP verb. With a RESTful web service, actions are taken on data resources using HTTP verbs like GET, POST, PUT, or DELETE. Each resource is accessible at a globally-unique URI. Because all API resources are available as HTTP-accessible endpoints, the RESTful design criteria enables data caching and is optimized to work with the web's distributed infrastructure.

The Admin Audit API's URI is:

GET https://www.googleapis.com/apps/reporting/audit/v1/customerId/applicationId/?parameters

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 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. The parameters are any parameters being applied to the query.

The full set of URIs used for each supported operation in the API is summarized in the Admin Audit API Using the API document.

Data formats

The JavaScript Object Notation (JSON) is the default format. JSON is a common Internet format that provides a simple method of representing arbitrary data structures. The Atom notation is an alternate data format. Both the JSON and Atom data formats support full read-write capabilities.

According to json.org, JSON is a text format that is completely language-independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others.

To change the API's data format, include the alt property in your request's URI. For example, if asking for all changes in your control panel and you want the report data returned using either the Atom or JSON alt values:

To return this data in the JSON format

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

To return this data in the Atom format

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

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.