- Download GAM
- Configure GAM
- Running GAM for the First Time
- More simple GAM commands
- Running GAM on Android or a Chromebook
- Using GAM with a HTTP Proxy
- Using GAM with SSL / TLS MitM Inspection
GAM is a command line tool that allows administrators to manage many aspects of their G Suite Account. This page provides simple instructions for downloading, installing and starting to use GAM.
GAM requires G Suite Business, Education, Partner or Government Edition. G Suite Legacy Free Edition has limited API support and not all GAM commands work.
While many GAM functions do not require domain administrative privileges, the setup does.
Head to the Releases page and download the latest Windows MSI version of GAM. The filename should look like
gam-4.02-windows-x64.msi (where 4.02 is the latest GAM version). Run the MSI installer. By default, GAM will install to
C:\GAM but you can change this to wherever you prefer. GAM will also be added to your path so you can run GAM even if you're not in the GAM folder.
At the end of the MSI install process, GAM will open a command prompt to allow you to setup a project and authorize GAM for admin management and user data/config access.
Mac and Linux Users
Open a shell prompt (Mac OS terminal app) and run:
bash <(curl -s -S -L https://git.io/install-gam)
make sure you type the command exactly as above (best to use copy and paste). The script will download the latest release of GAM and install it to your
After the script has downloaded and installed GAM it will prompt you to setup a project and authorize GAM for admin management and user data/config access.
If you're only updating your GAM install instead run this command.
bash <(curl -s -S -L https://git.io/install-gam) -l
To run any of the commands, GAM needs three things to complete the configuration:
- An API project which identifies your install of GAM to Google and keeps track of API quotas.
- Authorization to act as your G Suite Administrator.
- A special service account that is authorized to act on behalf of your users in order to modify user-specific settings and data such as Drive files, Calendars and Gmail messages and settings like signatures.
Creating a Project
If GAM isn't already prompting you to create a project, you can run:
gam create project
to get started.
- GAM will prompt you for your G Suite admin email address. Enter the address of a super admin in your G Suite instance.
- Depending on your choices, either a website will open automatically or you'll be given a URL to go to to authorize GAM to create projects as the admin you specified. Click allow, copy the code if given one and switch back to the GAM window.
- GAM will now create the project, turn on necessary Google APIs for the project such as Drive, Gmail, Admin SDK, etc and finally create a service account.
- Next, you'll be asked to go to a URL and perform a few actions to create a "OAuth client ID". Follow the steps as provided and copy the client ID and secret back into GAM when prompted.
- Now you are asked to return to the browser window and make a change to your new service account. Once you've enabled G Suite Domain-wide Delegation, return to the GAM console window.
Authorize Admin Access
- If you're not already prompted to authorize an admin as part of the install and configure process above, you can manually start the authorization by running
gam oauth create. You'll be prompted for the email address of a super admin in your G Suite domain.
- You'll be presented a long list of APIs that GAM can use. By default, the most important APIs are selected. Unless you know what you are doing you can leave this selection as is and press C to continue to authorization.
- GAM will either open a web page for you or prompt you with a URL to visit in order to authorize admin access. Visit the URL and Authorize. You may need to copy a code from the browser back to the GAM window.
- That's it, GAM is now authorized to perform admin actions.
Authorize User Data and Settings Access
- If you're not already prompted to authorize user data access as part of the install and configure process above, you can manually start the authorization process by running
gam user email@example.com check serviceaccount.
- GAM will prompt you for the email address of a regular, non-admin user in your G Suite domain. Make sure this user has the Gmail, Drive and Calendar services enabled. If the service is not enabled, GAM will fail to connect to that service for the user.
- Now GAM will attempt to authenticate with each service / scope via the service account and acting on behalf of the user you specified above. It's expected that the first time through these attempts will FAIL. GAM will provide you with a URL to visit, a "Client name" and a list of scopes. Visit the URL and copy the "Client name" and scopes. Pay special attention when copying the scopes that you don't accidentally cut off the full list of URLs.
- Once you've authorized the Client name for the scopes in the admin console, re-run the check by saying Y or running
gam user firstname.lastname@example.org check serviceaccountagain. It may take a few minutes after authorizing the scopes for all tests to PASS. If you've confirmed the Client name and scopes are listed properly on the website, grab a coffee and then try again.
That's it! GAM is now setup and ready to run.
Note : If you're getting a 401 error "client not found" from Google OAuth Authorisation, please check that the client_secrets.json file inside your gam directory matches your GSuite API client id and customer secrets (recursive creation of projects creates new files on the filesystem instead of overwriting the default one)
Running GAM for the First Time
Open a command prompt, shell or terminal on your computer. On Windows, you can do this by going to Start -> Programs -> Accessories -> Command Prompt. Now run:
gam info user
You'll be asked to specify which "scopes" you'd like the OAuth token to support. For now, select the last option to continue, all scopes will be selected. Next GAM will open up a web page in order for you to grant access to retrieve data and make changes to your G Suite account. Make sure you are logged in to a Google G Suite Administrator account before granting access. Once you've granted access, switch back to the command prompt window, GAM should already be working to display information about your user account.
Congrats, you're up and running with GAM.
More simple GAM commands
Try the following GAM commands to get a feel for how the program works. I suggest creating a test user account for experimenting, or if you don't have a test account, use your account, we'll call our test user crashtestdummy in the examples below.
If you haven't already, we can just create our crashtestdummy account with GAM:
gam create user crashtestdummy firstname Crash lastname "Test Dummy" password "BuckleUp"
We can give crashtestdummy an alias so that emails to idontwearseatbelts go to him:
gam create alias idontwearseatbelts user crashtestdummy
We can create a group for crash test dummy's friends:
gam create group test-dummies-united name "Test Dummies United" description "Support Group Against Plastic Abuse"
Crash test dummy likes Gmail but sometimes he prefers to use IMAP with his favorite email client, Thunderbird, let's enable IMAP for him:
gam user crashtestdummy imap on
these are just a few examples, more are available under the topics to the right. Have fun!
Running GAM on Android or a Chromebook
Using GAM with a HTTP Proxy
GAM should be run on a server with direct access to talk to Google servers via the Internet. However, if you must push GAM traffic through an HTTP proxy this can be done by setting the
HTTP_PROXY environment variable.
export HTTP_PROXY="http://192.168.1.1:3128" gam info domain
Using GAM with SSL / TLS MitM Inspection
By default, GAM verifies the Google HTTPS servers it talks to using public certificates signed by known certificate authorities. The authorities are listed in this file. GAM should be run on a server with direct access to talk to Google servers via the Internet, SSL / TLS inspection should NOT be used. If it must be used, you should assume that the SSL / TLS MitM proxy has complete access to your G Suite admin settings and user data (since it can see the unencrypted GAM API calls). You can tell GAM to check the SSL / TLS certificates against your own certificate authority file by setting the
GAM_CA_FILE which should point to a PEM formatted file which contains your certificate authority.