All of your API requests must be sent over HTTPS. Each API request that you send needs to contain an authentication token, which Google will use to authorize access to the operation specified in the API request. Authentication tokens are only available to users who have administrative rights in your domain, and those tokens only authorize operations within your domain.
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 Provisioning API service along with every subsequent request on behalf of that user.
For clients using ClientLogin and have been enrolled in two-step verification, use your two-step verification two-step verification access code for the Passwd query parameter.
For Google Apps accounts with multiple domains that are using the SAML protocol, see XML Formats for SAML Requests and Responses for more information about when to use the account's primary domain or an additional domain in these types of configuration.
ClientLogin username/password authentication
To obtain an authentication token, submit an HTTP POST request to the following URL:
The following guidelines apply to the request:
The POST body needs to include a string in the following format:&Email=<email_address>&Passwd=<password>&accountType=HOSTED&service=apps
You will need to make the following changes to this string:
Replace the string <email_address> with the email address for your admin account.
Replace the string <password> with the password or two-step verification two-step verification access code for that account.
The email address and password values must be URL-encoded. For example, the URL-encoded form of the email address firstname.lastname@example.org is apps%2Etest%2Eaccount%40example%2Ecom.
The POST request must specify the value application/x-www-form-urlencoded for the Content-Type header.
Google will return a response containing your authentication token in response to your POST request. The authentication token will be the Auth value on that page, and you need to extract the token from the page. When you submit an API request, you must set the Content-type and Authorization headers as shown in the example below.
Content-type: application/atom+xml Authorization: GoogleLogin auth=your-authentication-token
Note: Authentication tokens expire after 24 hours. As such, you will need to submit a request to the above URL at least once every 24 hours. We recommend that you keep the token in memory rather than writing it to a file. If you encounter a CAPTCHA challenge while obtaining an authentication token, the CAPTCHA section of the FAQ provides instructions on how you can handle it.
OAuth for web applications
Provisioning API service also supports 3-legged OAuth scheme for allowing web applications to manage users, nicknames, groups and organization units. The OAuth guide provides more information on how to obtain access tokens
OAuth scope parameter for groups
Use this OAuth access scope for groups.
- Groups resource -- https://apps-apis.google.com/a/feeds/group/2.0/domain/
OAuth scope parameter for nicknames and user aliases
- Nickname resource -- https://apps-apis.google.com/a/feeds/domain/nickname/2.0/
- User alias resource -- https://apps-apis.google.com/a/feeds/alias/2.0/domain/
OAuth scope parameter for organization units, organization users, and customerId
- customerId resource -- https://apps-apis.google.com/a/feeds/customer/2.0/customerId/
- Organization unit resource -- https://apps-apis.google.com/a/feeds/orgunit/2.0/
- Organization user resource -- https://apps-apis.google.com/a/feeds/orguser/2.0/
OAuth scope parameter for users
- Single domain user resource -- https://apps-apis.google.com/a/feeds/domain/user/2.0/
- Multi domain user resource -- https://apps-apis.google.com/a/feeds/user/2.0/domain/