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.

Google Apps Admin Audit API Authorization

The Admin Audit API is designed for multi-user web applications and uses the OAuth 2.0 and v1 standard protocols to authenticate each request and authorize the scope of each API report.

OAuth 2.0 is a new, simplified authorization protocol for Google APIs. OAuth 2.0 relies on SSL for security instead of requiring your application to do cryptographic signing directly. This protocol allows your application to request access to data associated with a user's Google Account.

The OAuth v1 protocol is a secure authentication and authorization service. This allows your web application to be given permission to access specific areas of your user's Google Apps data without revealing the users' names and passwords. The authentication examples in this document use the OAuth v1 delegated access 3-legged work flow which lets your web application access a Google Apps user's data hosted on the Google servers. When using OAuth v1, get an API key.

As your applications are extended using the full set of Google Apps APIs, you will implement a range of additional authentication and authorization protocols depending on the type of deployment. For more information about additional the Google Apps authentication and authorization protocols, see Choosing an Auth Mechanism.

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

OAuth scope parameter

Use the following scope for read only access to the Admin Audit API:

https://www.googleapis.com/auth/apps/reporting/audit.readonly

Use this scope for OAuth access to the customerId operation:

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

Getting and using a token credential

When setting up your OAuth credentials, determine your development environment, signature type and application registration. Then create your token credentials, and the OAuth signature.

For detailed OAuth information, see the OAuth reference and resources section of this document. And, if you are new to OAuth, we recommend the Beginner's Guide for OAuth.

Your development environment

We recommend using a Google API client library. For Java clients, see the Java OAuth client library Overview for detailed instructions for getting and using an OAuth token credential.

The OAuth examples in this document use the generic XML. The operation examples use JSON.

Determine your OAuth signature and register your application

Before building up your OAuth 1.0 configuration, determine the type of OAuth signature used by your client application, and register your web application with Google.

  • If your application requires enhanced security using the RSA-SHA1 signature, you must get your security certificate before registering your application with Google. The uploading of this certificate is part of the registration process. For more information, see Generating keys and certificates for use with registered mode.
  • If you use a HMAC-SHA1 signature to sign your requests, no security certificate is required. For the HMAC-SHA1 signature, Google generates an OAuth consumer secret value, which is displayed on your domain's registration page after you have registered.

For more information on the registration process, see Registration for Web Applications. For more information about registering, see 'Deciding whether to register your web application'. This gives you your client credential (consumer key and secret).

Note: Do not use the OAuth non-registered option where the consumer key and consumer secret properties have 'anonymous' values. The Admin Audit API feeds are available to Google registered applications only. And all of your application's OAuth interactions must be digitally signed.

Get a token credential

Follow these general steps to obtain an a token credential. For more information, see OAuth Authentication for Web Applications:
  1. Get your temporary token (request token). This token is used once. (OAuthGetRequestToken)
  2. Ask the user to authorize the request token (OAuthAuthorizeToken)
  3. Exchange the authorized request token for a token credential (access token). (OAuthGetAccessToken)

Create your OAuth signature

Once you have a valid token credential, your client application can send requests with an OAuth_signature, Authorization header, and for OAuth 1.0 clients, an API key. These examples use the RSA-SHA1 signature method.

  1. Create the signature base string. Note, the actual string is continuous. This example uses line returns for display purposes.
    GET&https://www.googleapis.com/apps/reporting/audit/v1/C03az79cb/207535951991
    &oauth_consumer_key=example.com&oauth_nonce=38863f48...28dd9fd2c
    &oauth_signature_method=RSA-SHA1&oauth_timestamp=1249972977
    &oauth_token=1%2Fz1...LMzNBrKhElA&oauth_version=1.0&key=YOUR-DEV-CONSOLE-KEY
    &endTime=2010-10-28T05:14:18.345Z&maxResults=1&actorEmail=john@example.com
  2. Set the oauth_signature to the result of signing the base string with the algorithm you specify in the oauth_signature_method. This requires URL-encoding the signature base string. Note, the string is continuous and this example uses line returns for display purposes.
    GET&https%3A%2%2Fwww.googleapis.com%2Fapps%2Freporting%2Faudit%2Fv1
    %2FC03az79cb%2FC207535951991%26%2F&oauth_consumer_key%3Dexample.com
    %26oauth_nonce%3D38863f48...28dd9fd2c%26oauth_signature_method%3DRSA-SHA1
    %26oauth_timestamp%3D1249972977%26oauth_token%3D1%252Fz1...LMzNBrKhElA
    %26oauth_version%3D1.0%26key%3DYOUR-DEV-CONSOLE-KEY
    %26endTime%3D2010-10-28T05:14:18.345Z%26maxResults%3D1
    %26actorEmail%3Djohn@example.com
  3. The Authorization header is similar to this example. Note, the string is continuous and this example uses line returns for display purposes.
    GET https://www.googleapis.com/apps/reporting/audit/v1/C03az79cb/207535951991
    ?endTime=2010-10-28T05:14:18.345Z&maxResults=1 
    ...
    Authorization: OAuth oauth_version="1.0", oauth_nonce="38863f48...28dd9fd2c", >oauth_timestamp="1249972977", oauth_consumer_key="example.com", oauth_token="1%2Fz1...LMzNBrKhElA", oauth_signature_method="RSA-SHA1", oauth_signature="kH%2BjQd%2Ba8...odMeUnsU%2FxANOw%3D", key=YOUR-DEV-CONSOLE-KEY

Additional OAuth reference and resources

Getting started

References

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.