GAM Documentation

Command line management for Google Workspace

4,163 stars Python Python 1 file · ~21,770 tokens #gam#google#google-admin-sdk#google-api#google-apps#google-calendar#google-cloud#google-drive
RAW Doc

File: README.md

GAM is a command line tool for Google Workspace admins to manage domain and user settings quickly and easily.

Quick Start

Linux / MacOS

Open a terminal and run:

sh
bash <(curl -s -S -L https://gam-shortn.appspot.com/gam-install)

this will download GAM, install it and start setup.

Windows

Download the EXE Installer from the GitHub Releases page. Run it and you'll be prompted to setup GAM.

Use your own Python

If you'd prefer to install GAM as a Python package you can install with pip:

text
pip install gam7

Documentation

The GAM documentation is hosted in the GitHub Wiki

Mailing List / Discussion group

The GAM mailing list / discussion group is hosted on Google Groups. You can join the list and interact via email, or just post from the web itself.

Chat Room

There is a public chat room hosted in Google Chat. Instructions to join.

Author

GAM is maintained by Jay (James) Lee and Ross Scroggs. Please direct "how do I?" questions to Google Groups.

File: wiki/_Sidebar.md

FAQ

Update History

Installation

Configuration

Notes and Information

Definitions

Command Processing

Collections

Client Access

Special Service Account Access

Service Account Access

File: wiki/00scratch.md

Scratch Me Wiki

editing these files shouldn't trigger a regular GitHub Action build.

Counter

00010

File: wiki/Addresses.md

Addresses

API documentation

Display addresses

Produces a three column CSV file (headers Type, Email, Target) that displays all group and user primary
email addresses and aliases; resource calendar addresses and domain names.

The types are:

text
DomainPrimary, DomainSecondary, DomainAlias
Group, GroupAlias, GroupNEAlias
Resource
SuspendedUser, SuspendedUserAlias, SuspendedUserNEAlias
User, UserAlias, UserNEAlias

'NE' is an abbreviation for NonEditable.

text
gam print addresses [todrive <ToDriveAttribute>*]
        [domain <DomainName>]

By default, groups and users in all domains in the account are selected; this options allows selection of subsets of groups and users:

  • domain <DomainName> - Limit groups and users to those in <DomainName>

File: wiki/Administrators.md

Administrators

API documentation

Definitions

text
<AdminAssigneeType> ::= group|user|serviceaccount|unknown
<AdminAssigneeTypeList> ::= "<AdminAssigneeType>(,<AdminAssigneeType>)*"
<DomainName> ::= <String>(.<String>)+
 ::= <String>@<DomainName>
<GroupItem> ::= ||<String>
<JSONData> ::= (json [charset <Charset>] <String>) | (json file <FileName> [charset <Charset>]) |
<OrgUnitID> ::= id:<String>
<OrgUnitPath> ::= /|(/<String)+
<OrgUnitItem> ::= <OrgUnitID>|<OrgUnitPath>
 ::= <String>
 ::= "(, ::= <String>
<RoleID> ::= <String>
<RoleName> ::= <String>
<RoleItem> ::= id:<RoleID>|<RoleName>
 ::= id:<String>
 ::= ||<String>

Display administrative privileges

text
gam print privileges [todrive <ToDriveAttribute>*]
gam show privileges

Here is the output from gam show privileges; use this to find a specific ``.

text
/* Detailed source-code truncated for AI context efficiency. */

Manage administrative roles

text
gam create adminrole <String> [description <String>]
        privileges all|all_ou||(select <FileSelector>|<CSVFileSelector>>)|<JSONData>
        [csv [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]] (addcsvdata <FieldName> <String>)*]
gam update adminrole <RoleItem> [name <String>] [description <String>]
        [privileges all|all_ou||(select <FileSelector>|<CSVFileSelector>>)|<JSONData>] 
        [csv [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]] (addcsvdata <FieldName> <String>)*]
gam delete adminrole <RoleItem>
  • privileges all - All defined privileges
  • privileges all_ou - All defined privileges than can be scoped to an OU
  • privileges - A specific list of privileges
  • privileges select <FileSelector>|<CSVFileSelector>> - A collection of privileges from a flat or CSV file

By default, when an admin role is created|update, GAM displays <RoleName>(<RoleID>) created|updated.

  • csv [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]] - Output the admin roledetails in CSV format.

When csv is uused, Add additional columns of data from the command line to the output.

  • addcsvdata <FieldName> <String>

Display administrative roles

text
gam info adminrole <RoleItem> [privileges]
        [formatjson]
  • privileges - Display privileges associated with role

By default, Gam displays the information as an indented list of keys and values.

  • formatjson - Display the fields in JSON format.
text
gam show adminroles|roles
        [role <RoleItem>] [privileges]
        [nosystemroles]
        [formatjson]
  • privileges - Display privileges associated with each role

By default, all roles are displayed:

  • role <RoleItem> - Display a specific role.
  • nosystemroles - Display onnly non-system roles.

By default, Gam displays the information as an indented list of keys and values.

  • formatjson - Display the fields in JSON format.
text
gam print adminroles|roles [todrive <ToDriveAttribute>*]
        [role <RoleItem>] [privileges] [oneitemperrow]
        [nosystemroles]
        [formatjson [quotechar <Character>]]
  • privileges - Display privileges associated with each role

By default, all privileges for a role are shown on one row as a repeating item.
When oneitemperrow is specified, each privilege is output on a separate row/line with the other role fields.

By default, all roles are displayed:

  • role <RoleItem> - Display a specific role.
  • nosystemroles - Display onnly non-system roles.

By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format:

  • formatjson - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain
the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled.
When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output.
The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output.
quotechar defaults to gam.cfg/csv_output_quote_char. When uploading CSV files to Google, double quote " should be used.

Create an administrator

Add an administrator role to an administrator.

text
gam create admin | <RoleItem> customer|(org_unit <OrgUnitItem>)
        [condition securitygroup|nonsecuritygroup] [expires <DateTime>]
  • customer - The administrator can manage all organization units
  • org_unit <OrgUnitItem> - The administrator can manage the specified organization unit

The option condition limits the conditions for delegate admin access. This currently only works with the _GROUPS_EDITOR_ROLE and _GROUPS_READER_ROLE roles.

  • condition securitygroup - limit the delegated admin to managing security groups
  • condition nonsecuritygroup - limit the delegated admin to managing non-security groups

The option expires <DateTime> specifies when the role assignment expires; it must be within one year.

Delete an administrator

Remove an administrator role from an administrator.

text
gam delete admin <RoleAssignmentId>

Display administrators

text
gam print admins [todrive <ToDriveAttribute>*]
        [user|group |] [role <RoleItem>]
        [types <AdminAssigneeTypeList>]
        [recursive] [condition] [privileges] [oneitemperrow]
gam show admins
        [user|group |] [role <RoleItem>]
        [types <AdminAssigneeTypeList>]
        [recursive] [condition] [privileges]

By default, all administrators and roles are displayed; choose from the following
options to limit the display:

  • user|group | - Display assignments to this administrator
  • role <RoleItem> - Display only administrators with this role

By default, all admin assignee types are displayed. use types <AdminAssigneeTypeList> to filter
admin assignments by the type of the assignee.

By default, assignments to security groups are displayed as a single item; use recursive
to display assignments to the members of the security groups; the security group membershop is recursively expanded.

  • condition - Display any conditions associated with a role assignment
  • privileges - Display privileges associated with each role assignment

By default, all role privileges for an admin are shown on one row as a repeating item.
When oneitemperrow is specified, each role privilege is output on a separate row/line with the other admin fields.

Copy privileges from one role to a new role

Get privileges for existing role; replace Role Name with actual role name

text
gam redirect csv ./RolePrivileges.csv print adminrole role 'Role Name' privileges oneitemperrow

Create a new role with those privileges

text
gam create adminrole "New Role Name" privileges select csvfile RolePrivileges.csv:privilegeName

Copy roles from one administrator to another

Get roles for current admin.

text
gam redirect csv ./CurrentAdminRoles.csv print admins user [email protected]

Add roles to new admin.

text
gam config csv_input_row_filter "scopeType:regex:CUSTOMER" redirect stdout ./UpdateNewAdminCustomerRoles.txt multiprocess redirect stderr stdout csv CurrentAdminRoles.csv gam create admin [email protected] "id:~~roleId~~" customer
gam config csv_input_row_filter "scopeType:regex:ORG_UNIT" redirect stdout ./UpdateNewAdminOrgUnitRoles.txt multiprocess redirect stderr stdout csv CurrentAdminRoles.csv gam create admin [email protected] "id:~~roleId~~" org_unit "id:~~orgUnitId~~"

Copy non-system admin roles from a source workspace to a target workspace

In the source workspace do the following:

text
gam redirect csv ./SourceNonSystemRoles.csv print adminroles privileges nosystemroles formatjson quotechar "'"

In the target workspacce do the following:

text
gam redirect csv ./TargetNonSystemRoles.csv multiprocess quotechar "'"  redirect stderr - multiprocess csv SourceNonSystemRoles.csv quotechar "'" gam create adminrole "~roleName" description "~roleDescription" privileges json "~JSON" csv addcsvdata oldRoleId "~roleId" formatjson

File: wiki/Alert-Center.md

Alert Center

API documentation

Query documentation

Definitions

text
<AlertID> ::= <String>
 ::= <String>
<QueryAlert> ::= <String> See: https://developers.google.com/admin-sdk/alertcenter/guides/query-filters

Introduction

For an introduction, start here: https://support.google.com/a/answer/9105393

This API is in beta, most things seem to work although the filter queries don't all work, in particular those that
select alertId and feedbackId.

To use these commands you must update your gam project and service account authorization.

text
gam update project
gam user [email protected] update serviceaccount

Manage alerts

text
gam delete alert <AlertID>
gam undelete alert <AlertID>

Display alerts

text
gam info alert <AlertID> [formatjson]
gam show alerts [filter <QueryAlert>] [orderby createtime [ascending|descending]]
        [formatjson]

By default, Gam displays the information as an indented list of keys and values.

  • formatjson - Display the fields in JSON format.
text
gam print alerts [todrive <ToDriveAttributes>*] [filter <QueryAlert>] [orderby createtime [ascending|descending]]
        [formatjson [quotechar <Character>]]

By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format,

  • formatjson - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain
the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled.
When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output.
The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output.
quotechar defaults to gam.cfg/csv_output_quote_char. When uploading CSV files to Google, double quote " should be used.

Eliminate unwanted fields

You can use CSV Print Filtering to reduce the amount of output.
This command will drop all of the data.messages columns.

text
gam config csv_output_header_drop_filter "^data.messages" redirect csv alerts.csv print alerts

Manage alert feedback

text
gam create alertfeedback <AlertID> not_useful|somewhat_useful|very_useful

Display alert feedback

text
gam show alertfeedback [alert <AlertID>] [filter <QueryAlert>] [orderby createtime [ascending|descending]]
        [formatjson]

By default, Gam displays feedback for all alerts.

  • alert <AlertID> - Display feedback for the selected alert
  • filter <QueryAlert> - Display feebback for the filtered alerts

By default, Gam displays the information as an indented list of keys and values.

  • formatjson - Display the fields in JSON format.
text
gam print alertfeedback [todrive <ToDriveAttributes>*] [alert <AlertID>] [filter <QueryAlert>] [orderby createtime [ascending|descending]]
        [formatjson [quotechar <Character>]]

By default, Gam displays feedback for all alerts.

  • alert <AlertID> - Display feedback for the selected alert
  • filter <QueryAlert> - Display feebback for the filtered alerts

By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format,

  • formatjson - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain
the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled.
When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output.
The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output.
quotechar defaults to gam.cfg/csv_output_quote_char. When uploading CSV files to Google, double quote " should be used.

Configuring settings

Alert Center can be configured to send notifications to a Google Cloud Pub/Sub topic, but it first requires configuration.

Gam can be used to display or modify the settings:

text
gam show alertsettings
gam update alertsettings 
gam clear alertsettings

File: wiki/Aliases.md

Aliases

API documentation

Query documentation

Definitions

See Collections of Items

text
<DomainName> ::= <String>(.<String>)+
<DomainNameList> ::= "<DomainName>(,<DomainName>)*"
<DomainNameEntity> ::=
        <DomainNameList> | <FileSelector> | <CSVFileSelector>
 ::= <String>@<DomainName>
 ::= "(,)*"
 ::=  | <FileSelector> | <CSVkmdSelector> | <CSVDataSelector>
        See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items
 ::= id:<String>

<RegularExpression> ::= <String>
        See: https://docs.python.org/3/library/re.html
<REMatchPattern> ::= <RegularExpression>
<RESearchPattern> ::= <RegularExpression>
<RESubstitution> ::= <String>>

Create an alias for a target

text
gam create alias|aliases  user|group|target |
        [verifynotinvitable]

are the aliases, is the target.

The verifynotinvitable option causes GAM to verify that the alias email address being created is not that of an unmanaged account;
if it is, the command is not performed.

Example

To allow Robert to also receive mail as Bob:

text
gam create alias bob[@yourdomain.com] user robert[@yourdomain.com]

Update an alias to point to a new target

The existing alias is deleted and a new alias is created.

text
gam update alias|aliases  user|group|target |
        [notargetverify] [waitafterdelete ]

are the aliases, is the target.

By default, GAM makes additional API calls to verify that the target email address exists before updating the alias;
if you know that the target exists, you can suppress the verification with `notargetverify.

GAM updates an alias to point to a new target by deleting the alias and then recreates the alias pointing to the new target.
Unfortunately, if these commands are executed back-to-back; Google generates the Update Failed: Duplicate error.
Now, GAM waits 2 seconds between the delete and the insert which seems to eliminate the problem. If the problem persists,
use the option waitafterdelete to increase the wait time to a maximum of 10 seconds.

Delete an alias regardless of the target

text
gam delete alias|aliases [user|group|target]

`` are the aliases.

Remove aliases from a specified target

text
gam remove alias|aliases  user|group

is the target, are the aliases.

Delete all of a user's aliases

text
gam  delete aliases

Display aliases

Display a specific alias.

text
gam info alias|aliases

Display selected aliases.

text
gam print aliases [todrive <ToDriveAttribute>*]
        ([domain|domains <DomainNameEntity>] [(query <QueryUser>)|(queries <QueryUserList>)]
         [limittoou <OrgUnitItem>])
        [user|users ] [group|groups ]
        [select ]
        [issuspended ] [isarchived ] [aliasmatchpattern <REMatchPattern>]
        [shownoneditable] [nogroups] [nousers]
        [onerowpertarget] [delimiter <Character>]
        [suppressnoaliasrows]
        (addcsvdata <FieldName> <String>)*

By default, group and user aliases in all domains in the account are selected; these options allow selection of subsets of aliases:

  • domain|domains <DomainNameEntity> - Limit aliases to those in the domains specified by <DomainNameEntity>
    • You can predefine this list with the print_agu_domains variable in gam.cfg.
  • (query <QueryUser>)|(queries <QueryUserList>) - Print aliases for users/groups that match a query; each query is run against each domain
  • limittoou <OrgUnitItem> - Print aliases for users in the specified <OrgUnitItem>
  • user|users - Print aliases for users in - Print aliases for users in
  • group|groups - Print aliases for groups in `` - Limit users based on their status
  • isarchived - Limit users based on their status
  • aliasmatchpattern <REMatchPattern> - Print aliases that match a pattern
  • nogroups - Print only user aliases
  • nousers - Print only group aliases

By default, the CSV output has three columns: Alias,Target,TargetType; if a target
has multiple aliases, there will be multiple rows, one per alias.

Use shownoneditable to list non-editable alias email addresses; these are typically outside of the account's primary domain or subdomains.
This adds the column NonEditableAlias.

Specifying onerowpertarget changes the three columns to: Target,TargetType,Aliases; all aliases for the target are listed in the
Aliases column. If shownoneditable is specified, there will be a fourth column NonEditableAliases with a list of non-editable aliases.

By default, the aliases in a list are separated by the csv_output_field_delimiter' from gam.cfg`.

  • delimiter <Character> - Separate aliases in a list with <Character>

Specifying both onerowpertarget and suppressnoaliasrows causes GAM to not display any targets that have no aliases.

Add additional columns of data from the command line to the output

  • addcsvdata <FieldName> <String>

When multiple domains are specified and a query/queries are specified, an API call is made for each domain/query combination.

text
$ gam print aliases domains school.org,students.school.org queries "'email:admin*','email:test*'"
Getting all Users that match query (domain=school.org, query="email:admin*"), may take some time on a large Google Workspace Account...
Got 3 Users: [email protected] - [email protected]
Getting all Users that match query (domain=school.org, query="email:test*"), may take some time on a large Google Workspace Account...
Got 20 Users: [email protected] - [email protected]
Getting all Users that match query (domain=students.school.org, query="email:admin*"), may take some time on a large Google Workspace Account...
Got 1 User: [email protected] - [email protected]
Getting all Users that match query (domain=students.school.org, query="email:test*"), may take some time on a large Google Workspace Account...
Got 1 User: [email protected] - [email protected]
Alias,Target,TargetType
...

Bulk delete aliases

You can bulk delete aliases by using gam print aliases to list the aliases to be deleted and then deleting them.

text
gam redirect csv ./Aliases.csv print aliases domain olddomain.com  onerowpertarget suppressnoaliasrows
gam redirect csv ./Aliases.csv print aliases aliasmatchpattern ".*@olddomain.com" onerowpertarget suppressnoaliasrows
gam redirect stdout ./DeleteAliases.txt multiprocess redirect stderr stdout csv ./Aliases.csv gam remove aliases "~Target" "~TargetType" "~Aliases"

Bulk reassign aliases

You can bulk reassign aliases as follows. Make a CSV file ReassignAliases.csv with two columns: OldTarget,NewTarget.
From this CSV file, all of the aliases for the users in the OldTarget column will be listed with an additional column showing the NewTarget.

text
gam redirect stdout ./GetAliases.txt multiprocess redirect stderr stdout redirect csv ./ReassignAliases.csv gam print aliases user "~OldTarget" addcsvdata NewTarget "~NewTarget"

If an OldTarget's aliases are to be reassigned to more than the one NewTarget, edit ReassignAliases.csv and make changes as required.

text
gam redirect stdout ./ReassignAliases.txt multiprocess redirect stderr stdout csv ReassignAliases.csv gam update alias "~Alias" user "~NewTarget"

Determine if an address is a user, user alias, group or group alias

text
gam whatis  [noinfo] [noinvitablecheck]

The first line of output is: <TypeOfEmailItem>:

There is additional output based on <TypeOfEmailItem>:

  • User - gam info user
  • Group - gam info group
  • User Alias - gam info alias
  • Group Alias - gam info alias
  • User Invitation - gam info userinvitation

The noinfo argument suppresses the additional output.

The noinvitablecheck argument suppresses the user invitation check
to avoid exceeding quota limits when checking a large number of addresses.

The return code is set based on <TypeOfEmailItem>:

  • User - 20
  • User Alias - 21
  • Group - 22
  • Group Alias - 23
  • User Invitation - 24
  • Unknown - 59

File: wiki/Authorization.md

Authorization

Introduction

GAM requires authorization to perform tasks on your domain; the tasks break down into two categories:

  • Client - Manipulate objects in the domain; the Client acts on its own behalf to perform the tasks. Examples: add a user, update a group, delete a class, share a printer.
  • Service Account - Manipulate objects that belong to users; the Service Account acts on behalf of the user to perform the tasks. Examples: view user files, calendars.

You create projects that define these authorizations.

Verify the following steps:

  • See https://support.google.com/a/answer/9197205?hl=en
  • Access the admin console and go to Apps -> Additional Google Services
  • Look for the service "Google Cloud Platform", click it
  • Expand "Service status"
  • Select the OU in the left that contains the super admin you'll be using
  • Make sure that "Service status" is ON
  • If groups are used to authenticate access, make sure the super admin is in one of the groups
  • Collapse "Service status"
  • Expand "Cloud Resource Manager API settings"
  • Select the OU in the left that contains the super admin you'll be using
  • Make sure that "Allow users to create projects" is checked

Verify that all scopes are available:

  • Access the admin console and go to Apps -> Additional Google Services
  • If this line is present: Access to additional services without individual control for all organizational units is turned Off
  • Click "CHANGE"
  • Select "ON for everyone"
  • Click "SAVE"

If you run a Google Workspace Education SKU, verify that Classroom API is enabled if required.

  • Access the admin console and go to Apps -> Google Workspace - Classroom
  • Expand "Data access"
  • Check "Users can authorize apps to access their Google Classroom data."
  • Click "SAVE"

If you run a Google Workspace Education SKU, verify that the super admin you'll be using is in an OU where "All users are 18 or older".

  • Access the admin console and go to Accounts -> Account settings
  • Expand "Age based access settings"
  • Select the OU containing the super admin
  • Choose "All users are 18 or older"
  • Click "SAVE"

Based on your domain policies, you may have to mark GAM as a trusted app. These steps are performed after a project is created.

  • Access the admin console and go to Security -> Access and data control -> API controls
  • Click Manage third-party app access
  • Click Configure new app
  • Paste client_id value from client_secrets.json in Search for app
  • Click Search
  • Click the line referencing GAM
  • Keep the default scope All in domain.com (all users) or select an org unit that includes your GAM admin
  • Click Continue
  • Click Trusted: App can request access to all Google data
  • Click Continue
  • Click Finish
  • Press Confirm if Confirm parental consent pops up

Verify whether the super admin you'll be using is in an OU where reauthentication is required.

  • Access the admin console and go to Security -> Overview
  • Scroll down and open Google Cloud session control section
  • Select the OU containing the super admin
  • If Require reauthentication is selected, you'll need either:
    • uncheck Google Cloud Storage and any other GCP APIs that you selected on gam oauth create (reauth is only necessary for GCP APIs)
    • enable "Exempt Trusted apps"
    • rerun gam oauth create at whatever frequency is specified

Additional steps may be required if errors are encountered.

Headless computers and Cloud Shells

With many thanks to Jay, gam oauth create now uses a new client access authentication flow
as required by Google for headless computers/cloud shells; this is required as of February 28, 2022.

API documentation

Definitions

text
<APIScopeURL> ::= <String>
<APIScopeURLList> ::= "<APIScopeURL>(,<APIScopeURL>)*"
 ::= <String>
        Must match this Python Regular Expression: [a-z][a-z0-9-]{4,28}[a-z0-9]
 ::= "(,)*"
 ::=
        current | gam |  | (filter <String>) |
        (select  | <FileSelector> | <CSVFileSelector>)
        See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items
 ::= <String>
        Must match this Python Regular Expression: [a-zA-Z0-9 '"!-]{4,30}
<ServiceAccountName> ::= <String>
        Must match this Python Regular Expression: [a-z][a-z0-9-]{4,28}[a-z0-9]
<ServiceAccountDisplayName> ::= <String>
        Maximum of 100 characters
<ServiceAccountDescrition> ::= <String>
        Maximum of 256 characters
<ServiceAccountEmail> ::= <ServiceAccountName>@.iam.gserviceaccount.com
<ServiceAccountUniqueID> ::= <Number>
<ServiceAccountKey> ::= <String>

Manage Projects

In all of the project commands, the Google Workspace admin/GCP project manager `` can be omitted; you will be prompted for a value.
You must enter a full address, i.e., [email protected]; you will be required to authenticate.

For print|show projects, you can eliminate the password prompt and authentication requirement by specifying the super admin emailaddress used in gam oauth create.

text
gam print projects admin [email protected]

Authorize a user to create projects

If you try to create a project and get an error saying that the user you specified is not authorized to create projects,
perform these steps and then retry the create project command.

  • Login as an existing super admin at console.cloud.google.com
  • In the upper left click the three lines to the left of Google Cloud and select IAM & Admin
  • Under IAM & Admin select IAM
  • Click in the box to the right of Google Cloud
  • Click the three dots at the right and select IAM/Permissions
  • Now you should be at "Permissions for organization ..."
  • Click on Grant Access
  • Enter the new admin address in Principals
  • Click in the Select a role box
  • Type project creator in the Filter box
  • Click Project Creator
  • Click Save

Authorize Service Account Key Uploads

IMPORTANT: Google best practice is to NOT use service account keys. Rather than overriding Google's default policy please consider Running GAM7 securely on a Google Compute Engine (if running in Google Cloud) or Workload Identity Federation (if running outside Google Cloud) so that service account keys are not necessary.

If you try to create a project and get an error saying that Constraint constraints/iam.disableServiceAccountKeyUpload violated for service account projects/gam-project-xxxxx,
perform these steps and then you should be able to authorize and use your project.

  • Login as an existing super admin at console.cloud.google.com
  • In the upper left click the three lines to the left of Google Cloud and select IAM & Admin
  • Under IAM & Admin select IAM
  • Click in the box to the right of Google Cloud
  • Click the three dots at the right and select IAM/Permissions
  • Now you should be at "Permissions for organization ..."
  • Click on Grant Access
  • Enter the new admin address in Principals
  • Click in the Select a role box
  • Type orgpolicy.policyAdmin in the Filter box
  • Click Organization Policy Administrator
  • Click Save
  • In the upper left click the three lines to the left of Google Cloud and select IAM & Admin
  • Under IAM & Admin select IAM
  • Click in the box to the right of Google Cloud
  • Click the three dots at the right and select Manage Resources
  • Click the three dots at the end of the line for the GAM project just created
  • Click Settings
  • Click Organization Policies in the left column
  • Now you should be at "Policies for Gam Project"
  • Click in the Filter box
  • Enter iam.managed.disableServiceAccountKeyUpload
  • Click the three dots at the end of the Disable service account key upload/iam.managed.disableServiceAccountKeyUpload line
  • Choose Edit policy
  • Click Override parent's policy
  • Click Add A Rule
  • Select Enforcement/Off
  • Click Done
  • Click Set Policy
  • Click the three dots at the end of the Disable Service Account Key Upload/iam.disableServiceAccountKeyUpload line
  • Choose Edit policy
  • Click Override parent's policy
  • Click Add A Rule
  • Select Enforcement/Off
  • Click Done
  • Click Set Policy

Wait a couple of minutes for the policy updates to complete and then do the following to upload the service account key:

text
gam upload sakey [admin ]

Authorize GAM to create projects

If you try to create a project and get an error saying "This app has been blocked on your domain for either being
insecure or non-edutational"; you'll have to mark the GAM Project Creation app as trusted.
Perform these steps and then retry the create project command.

  • Access the admin console and go to Security -> Access and data control -> API controls
  • Click Manage third-party app access
  • Click Add app and select OAuth App Name Or Client ID
  • Paste 297408095146-fug707qsjv4ikron0hugpevbrjhkmsk7.apps.googleusercontent.com
  • Click Search
  • Click Select at right end of line referencing GAM Project Creation
  • Check box to the left of the line with GAM Project Creation client ID
  • Click Select
  • Keep the default scope domain.com (all users) or select an org unit that includes your GAM admin
  • Click Next/Continue
  • Click Trusted: App can request access to all Google data
  • Click Next/Continue
  • Click Finish/Confirm

Create a new GCP project folder

This folder can be used in a subsequent gam create project parent <String> command.

text
gam create gcpfolder <String>
gam create gcpfolder [admin

Create a new project for GAM authorization

Create a new project to create and download two files: client_secrets.json for the Client and oauth2service.json for the Service Account.
On-screen instructions lead you through the process.

An existing project, GAM Project Creation, is used to create your GAM project. The initial instructions tell you how to
enable this project as a trusted app as your workspace may not allow untrusted third-party apps.
This is recommended but not mandatory unless your workspace has "Google Cloud" service restricted:

If it is restricted and you complete this step it may take an hour or so to take full affect and allow you to approve GAM project creation.

The final instructions tell you how to enable your new GAM project as a trusted app as your workspace may not allow untrusted third-party apps.
You can skip these steps if you know that untrusted third-party apps are allowed.

Default values

  • <AppName> - "GAM"
  • `` - "gam-project-a1b2c" where "a1b2c" are randomly generated
  • `` - "GAM Project"
  • <ServiceAccountName> - ``
  • <ServiceAccountDisplayName> - ``
  • <ServiceAccountDescription> - <ServiceAccountDisplayName>

Basic Create

Create a project with default values for the project and service account.

text
gam create project [] []
  • `` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address
  • `` - A new Google project ID; if omitted, a default value will be used

Advanced Create

Create a project with user-specified values for the project and service account.

text
gam create project [admin ] [project ]
        [appname <String>] [supportemail ]
        [projectname ] [parent <String>]
        [saname <ServiceAccountName>] [sadisplayname <ServiceAccountDisplayName>]
        [sadescription <ServiceAccountDescription>]
        [(algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)|
         (localkeysize 1024|2048|4096 [validityhours <Number>])|
         (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)|
         nokey}
  • admin - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address
  • appname <String> - Application name, defaults to GAM
  • supportemail - Administrator to contact about GAM authentication, defaults to admin
  • project - A new Google project ID; if omitted, a default value will be used
  • projectname - Google project name, defaults to "GAM Project"
  • parent <String> - A Resource Manager folder name
  • saname <ServiceAccountName> - Service account name; combined with `` to form <ServiceAccountEmail>
  • sadisplayname <ServiceAccountDisplayName> - Service account display name
  • sadescription <ServiceAccountDescription> - Service account description

You can optionally specify the type of service account key with algorithm|localkeysize|yubikey: Manage Service Account keys

Use nokey if you do not want a service account key created for the project.

Use an existing project for GAM authorization

To use the same GAM project on multiple computers, see: GAM Configuration

Use an existing project to create and download two files: client_secrets.json for the Client and oauth2service.json for the Service Account.

Default values

  • <ServiceAccountName> - ``
  • <ServiceAccountDisplayName> - ``
  • <ServiceAccountDescription> - <ServiceAccountDisplayName>

Basic Use

Use an existing uninitialized/uncredentialed project and configure it to be a GAM project; this typically used when
the GCP administrators have created a basic project because project creation is not available for most users.

See Jay's notes about how to do this: https://github.com/GAM-team/GAM/wiki/GAM-with-minimal-GCP-rights

text
gam use project [] [project ]
  • `` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address
  • `` - An existing Google project ID; if omitted, you will be prompted for the ID

Advanced Use

Use an existing project with user-specified values for the service account. If the project is already
a GAM project you must use saname <ServiceAccountName> as the existing service account information
can not be re-downloaded.

text
gam use project [admin ] [project ]
        [appname <String>] [supportemail ]
        [saname <ServiceAccountName>] [sadisplayname <ServiceAccountDisplayName>]
        [sadescription <ServiceAccountDescription>]
        [(algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)|
         (localkeysize 1024|2048|4096 [validityhours <Number>])|
         (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)]
  • admin - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address
  • project - An existing Google project ID; if omitted, you will be prompted for the ID
  • saname <ServiceAccountName> - Service account name; combined with `` to form <ServiceAccountEmail>
  • sadisplayname <ServiceAccountDisplayName> - Service account display name
  • sadescription <ServiceAccountDescription> - Service account description

You can optionally specify the type of service account key with algorithm|localkeysize|yubikey: Manage Service Account keys

Update an existing project for GAM authorization

This command is used when GAM has added new capabilities that require additional APIs to be added to your project.

text
gam update project [[admin] ] []
  • `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address

Use these options to select projects.

  • current - The project referenced in client_secrets.json; this is the default
  • gam - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with gam-project-
  • `` - A Google API project ID
  • filter <String> - A filter to select projects accessible by the administrator; see the API documentation

Delete an existing project for GAM authorization

text
gam delete project [[admin] ] []
  • `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address

Use these options to select projects.

  • current - The project referenced in client_secrets.json; this is the default
  • gam - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with gam-project-
  • `` - A Google API project ID
  • filter <String> - A filter to select projects accessible by the administrator; see the API documentation

Display projects

Display the current Project ID.

text
gam info currentprojectid

Display Google API projects as an indented list of keys and values.

text
gam show projects [[admin] ] [all|]
        [states all|active|deleterequested] [showiampolicies 0|1|3]
  • `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address

Use these options to select projects.

  • all - All projects accessible by the administrator
  • current - The project referenced in client_secrets.json
  • gam - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with gam-project-; this is the default
  • `` - A Google API project ID
  • filter <String> - A filter to select projects accessible by the administrator; see the API documentation
  • states all|active|deleterequested - Limit display to projects based on state; the default is active

Use the showiampolicies 0|1|3 option to display IAM policy information for the project.

Display Google API projects as columns of fields.

text
gam print projects [[admin] ] [all|] [todrive <ToDriveAttribute>*]
        [states all|active|deleterequested] [showiampolicies 0|1|3 [onememberperrow]]
        [delimiter <Character>]] [[formatjson [quotechar <Character>]]
  • `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address

Use these options to select projects.

  • all - All projects accessible by the administrator
  • current - The project referenced in client_secrets.json
  • gam - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with gam-project-; this is the default
  • `` - A Google API project ID
  • filter <String> - A filter to select projects accessible by the administrator; see the API documentation
  • states all|active|deleterequested - Limit display to projects based on state; the default is active

Use the showiampolicies 0|1|3 option to display IAM policy information for the project. Each role in the policy will be displayed on
a separate row; by default, all members will be shown on that row. By default, the members are separated by
the csv_output_field_delimiter from gam.cfg.

  • delimiter <Character> - Separate list items with <Character>

Use the onememberperrow option to show separate rows for each role/member combination.

By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format,

  • formatjson - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain
the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled.
When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output.
The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output.
quotechar defaults to gam.cfg/csv_output_quote_char. When uploading CSV files to Google, double quote " should be used.

Manage Client credentials

Create Client credentials

text
gam oauth|oauth2 create|request []
gam oauth|oauth2 create|request [admin ] [scopes <APIScopeURLList>]
  • `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address
  • scopes <APIScopeURLList> - A set of specific scopes; if omitted, you will be prompted to select your desired scopes.

You select a list of scopes, GAM uses a browser to get final authorization from Google for these scopes and
writes the credentials into the file oauth2.txt.

text
/* Detailed source-code truncated for AI context efficiency. */

Update Client credentials

text
gam oauth update []
gam oauth update [admin ]
  • `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address

Read API scopes from any version of oauth2.txt and select a list of APIs; GAM uses a browser to get final authorization from Google for these APIs and
writes the credentials into the file oauth2.txt.

text
/* Detailed source-code truncated for AI context efficiency. */

If you have multiple sections in gam.cfg that reference different oauth2.txt files, perform an update on each section:

text
gam select aaa oauth update
gam select bbb oauth update
...

Refresh Client credentials

Refresh the expiration time in oauth2.txt.

text
gam oauth refresh

If you have multiple sections in gam.cfg that reference different oauth2.txt files, perform a refresh on each section:

text
gam select aaa oauth refresh
gam select bbb oauth refresh
...

Delete Client credentials

text
gam oauth|oauth2 delete|revoke

Revoke the credentials in the file oauth2.txt and then delete the file.

Verify Client credentials

text
<AccessToken> ::= <String>
 ::= <String>
gam oauth|oauth2 info|verify [showsecret] [accesstoken <AccessToken> idtoken ] [showdetails]

The Client Secret is not shown by default, user showsecret to have it displayed.

These options are used for debugging: accesstoken <AccessToken> idtoken showdetails.

Export Client credentials

Export oauth2.txt in JSON form.

text
gam oauth|oauth2 export [<FileName>]
  • If <FileName> is omitted, the JSON data is written to oauth2.txt.
  • If <FileName> is -, the JSON data is written to stdout.

Manage Service Accounts

In all of the service account commands, the Google Workspace admin/GCP project manager `` can be omitted; you will be prompted for a value.
You must enter a full address, i.e., [email protected]; you will be required to enter the password.

Add Service Accounts to projects

You can add additional service accounts to a project and assign it specific access APIs. This command
creates a new oauth2service.json file; it will not overwrite an existing file so you must rename the existing
file or define a new section in gam.cfg that references a different oauth2service_json or config_dir.

Default values

  • <ServiceAccountName> - "gam-svcacct-abc-def-jki" where "abc-def-ghi" are randomly generated
  • <ServiceAccountDisplayName> - <ServiceAccountName>
  • <ServiceAccountDescription> - <ServiceAccountDisplayName>
text
gam create|add svcacct [[admin] ] []
        [saname <ServiceAccountName>] [sadisplayname <ServiceAccountDisplayName>]
        [sadescription <ServiceAccountDescription>]
        [(algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)|
         (localkeysize 1024|2048|4096 [validityhours <Number>])|
         (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)]
  • `` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address

Use these options to select projects.

  • current - The project referenced in client_secrets.json; this is the default
  • gam - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with gam-project-
  • `` - A Google API project ID
  • filter <String> - A filter to select projects accessible by the administrator; see the API documentation

Use these options to select user-specified values..

  • saname <ServiceAccountName> - Service account name; combined with `` to form <ServiceAccountEmail>
  • sadisplayname <ServiceAccountDisplayName> - Service account display name
  • sadescription <ServiceAccountDescription> - Service account description

You can optionally specify the type of service account key with algorithm|localkeysize|yubikey: Manage Service Account keys

After adding an additional service account, you can select specific access APIs for it.
Selective Service Account access

Delete Service Accounts from projects

text
gam delete svcacct [[admin] ] []
        (saemail <ServiceAccountEmail>)|(saname <ServiceAccountName>)|(sauniqueid <ServiceAccountUniqueID>)
  • `` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address

Use these options to select projects.

  • current - The project referenced in client_secrets.json; this is the default
  • gam - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with gam-project-
  • `` - A Google API project ID
  • filter <String> - A filter to select projects accessible by the administrator; see the API documentation

Display Service Accounts for projects

Display Service Accounts as an indented list of keys and values.

text
gam show svcaccts [[admin] ] [all|]
        [showsakeys all|system|user]

Display Service Accounts as columns of fields.

text
gam print svcaccts [[admin] ] [all|]
        [showsakeys all|system|user]
        [todrive <ToDriveAttribute>*] [formatjson [quotechar <Character>]]
  • `` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address

Use these options to select projects.

  • all - All projects accessible by the administrator; this is the default
  • current - The project referenced in client_secrets.json
  • gam - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with gam-project-
  • `` - A Google API project ID
  • filter <String> - A filter to select projects accessible by the administrator; see the API documentation

By default, no Service Account key information is displayed, use the following options to display keys.

  • showsakeys all - Display system and user keys; this is the default when keys are displayed
  • showsakeys system - Display system keys
  • showsakeys user - Display user keys

Manage Service Account keys

The oauth2service.json file contains a private key that is used to authenticate Service Account access.
This private key will be referred to as the current private key.

Each Service Account in a project typically has one private key but it can have multiple keys; this might be the
case if you have several users with Gam access where they will all access the same Service Account but with different keys.
You will distribute different oauth2service.json files to each user, each with its own private key.

There are several methods for generating private keys:

  • algorithm KEY_ALG_RSA_1024 - Google generates a 1024 bit key; not recommended
  • algorithm KEY_ALG_RSA_2048 - Google generates a 2048 bit key
  • localkeysize 1024 - Gam generates a 1024 bit key; this is not recommended
  • localkeysize 2048 - Gam generates a 2048 bit key; this is the default
  • localkeysize 4096 - Gam generates a 4096 bit key
  • yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)] - Using GAM7 with a YubiKey

When localkeysize is specified, the optional argument validityhours <Number> sets the length of time during which the key will be valid and should be used when the GCP constraints/iam.serviceAccountKeyExpiryHours organization policy is in use. Note that in order to account for system clock skew, GAM sets the key to be valid two minutes earlier than the current system time and thus it will also expire two minutes earlier.

Here are some sample values:

text
1 hour
   8 hours
  24 hours ( 1 day)
 168 hours ( 7 days)
 336 hours (14 days)
 720 hours (30 days)
1440 hours (60 days)
2160 hours (90 days)

Create a new Service Account key

Create a new Service Account private key; all existing private keys remain valid.
The oauth2service.json file is updated with the new private key.

This command requires that the current Service Account private key is valid, if you get the following error:

text
ERROR: 401: authError - Request had invalid authentication credentials.
Expected OAuth 2 access token, login cookie or other valid authentication credential.
See https://developers.google.com/identity/sign-in/web/devconsole-project.

see: Upload a Service Account key to a service account without a valid private key

Keep a good record of where each Service Account key is used as the keys themselves do not record this information.

The two forms of the command are equivalent; the second form is used by Legacy GAM.

text
gam create sakey
        (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)|
        (localkeysize 1024|2048|4096 [validityhours <Number>])|
        (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)
gam rotate sakey retain_existing
        (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)|
        (localkeysize 1024|2048|4096 [validityhours <Number>])|
        (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)

To distribute oauth2service.json files with unique private keys perform the following steps:

text
copy oauth2service.json to oauth2service.save
repeat
  gam create sakeys retain_existing
  distribute updated oauth2service.json file
  copy oauth2service.save to oauth2service.json

Update an existing Service Account key

Revoke the current Service Account key and replace it with a new private key; all other private keys remain valid.
The oauth2service.json file is updated with the new private key. If you had previously distributed
this oauth2service.json file to other users, you must redistribute the updated file as the private key
in the distributed copies has been revoked.

This command requires that the current Service Account private key is valid, if you get the following error:

text
ERROR: 401: authError - Request had invalid authentication credentials.
Expected OAuth 2 access token, login cookie or other valid authentication credential.
See https://developers.google.com/identity/sign-in/web/devconsole-project.

see: Upload a Service Account key to a service account without a valid private key

The two forms of the command are equivalent; the second form is used by Legacy GAM.

text
gam update sakey
        (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)|
        (localkeysize 1024|2048|4096 [validityhours <Number>])|
        (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)
gam rotate sakey replace_current
        (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)|
        (localkeysize 1024|2048|4096 [validityhours <Number>])|
        (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)

Replace all existing Service Account keys

Create a new Service Account private key; all existing private keys are revoked.
The oauth2service.json file is updated with the new private key. If you had previously distributed
any oauth2service.json file to other users, you must redistribute the updated file as the private key
in the distributed copies has been revoked.

This command can be used if your Service Account keys have been compromised; all existing private keys are revoked.

This command requires that the current Service Account private key is valid, if you get the following error:

text
ERROR: 401: authError - Request had invalid authentication credentials.
Expected OAuth 2 access token, login cookie or other valid authentication credential.
See https://developers.google.com/identity/sign-in/web/devconsole-project.

see: Upload a Service Account key to a service account without a valid private key

The two forms of the command are equivalent; the second form is used by Legacy GAM.

text
gam replace sakeys
        (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)|
        (localkeysize 1024|2048|4096 [validityhours <Number>])|
        (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)
gam rotate sakeys retain_none
        (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)|
        (localkeysize 1024|2048|4096 [validityhours <Number>])|
        (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)

Delete Service Account keys

You can delete Service Accounts keys thus revoking access for that key. Generally, you will
delete a service account key for a distributed copy of an oauth2service.json file to disable
that user's service account access.

This command requires that the current Service Account private key is valid, if you get the following error:

text
ERROR: 401: authError - Request had invalid authentication credentials.
Expected OAuth 2 access token, login cookie or other valid authentication credential.
See https://developers.google.com/identity/sign-in/web/devconsole-project.

see: Upload a Service Account key to a service account without a valid private key

You can disable your current Service Account key if you specify the doit argument. This is your
acknowledgement that you will have to manually create a new Service Account key in the Developer's Console
or upload a new key with the gam upload sakey command.

text
gam delete sakeys <ServiceAccountKeyList>+ [doit]

Display Service Account keys

There are system keys and user keys; user keys are what Gam uses; GCP uses system keys.

Display Service Account keys as an indented list of keys and values.

text
gam show sakeys [all|system|user]
  • all - Display system and user keys; this is the default
  • system - Display system keys
  • user - Display user keys

The private key currently being used in oauth2service.json will be marked as usedToAuthenticateThisRequest: True.

Upload a Service Account key to a service account without a valid private key

There are two cases where you will use this command:

  • Your workspace is configured to disable service account private key uploads and you are creating a project.
  • All of your service account keys have been deleted, either manually or with the gam delete sakeys command.

The oauth2service.json file is updated with the new private key. If you had previously distributed
any oauth2service.json file to other users, you must redistribute the updated file with the new key.

text
gam upload sakey [admin ]
        (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)|
        (localkeysize 1024|2048|4096 [validityhours <Number>])|
        (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber <Number>)

Manage Service Account access

Full Service Account access

Verify that the Service Account credentials have been authorized. If they have not, you will be given instructions
as to how to perform the authorization.
By default, the following scopes are verified:

text
https://mail.google.com/
https://sites.google.com/feeds
https://www.googleapis.com/auth/analytics.readonly
https://www.googleapis.com/auth/apps.alerts
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/chat.delete
https://www.googleapis.com/auth/chat.memberships
https://www.googleapis.com/auth/chat.messages
https://www.googleapis.com/auth/chat.spaces
https://www.googleapis.com/auth/classroom.announcements
https://www.googleapis.com/auth/classroom.coursework.students
https://www.googleapis.com/auth/classroom.courseworkmaterials
https://www.googleapis.com/auth/classroom.profile.emails
https://www.googleapis.com/auth/classroom.profile.photos
https://www.googleapis.com/auth/classroom.rosters
https://www.googleapis.com/auth/classroom.topics
https://www.googleapis.com/auth/cloud-identity
https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/contacts
https://www.googleapis.com/auth/contacts.other.readonly
https://www.googleapis.com/auth/datastudio
https://www.googleapis.com/auth/directory.readonly
https://www.googleapis.com/auth/documents
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/drive.activity
https://www.googleapis.com/auth/drive.admin.labels
https://www.googleapis.com/auth/drive.labels
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
https://www.googleapis.com/auth/keep
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/tasks
https://www.googleapis.com/auth/userinfo.profile

This scope is verified when user_service_account_access_only = true in gam.cfg.

text
https://www.googleapis.com/auth/apps.groups.migration

Verify/enable service account access for the default list of APIs.
The two forms of the command are equivalent.

text
gam check svcacct  (scope|scopes <APIScopeURLList>)*
gam  check serviceaccount (scope|scopes <APIScopeURLList>)*
  • `` - Typically user , a non-Google Workspace administrator.
  • scopes <APIScopeURLList> - Verify/enable service account access for a set of specific scopes rather than the default list.

Selective Service Account access

Verify/enable service account access for a selected list of APIs rather than the default list.
The two forms of the command are equivalent.

If scopes <APIScopeURLList> is not specified, you will be prompted to select a list of scopes.

text
gam update svcacct  (scope|scopes <APIScopeURLList>)*
gam  update serviceaccount (scope|scopes <APIScopeURLList>)*
  • `` - Typically user , a non-Google Workspace administrator.
  • scopes <APIScopeURLList> - Verify/enable service account access for a set of specific scopes rather than selecting the scopes.
text
/* Detailed source-code truncated for AI context efficiency. */

Configure Limited access

You can configure GAM to allow users limited access to your domain via GAM.
You can limit both client and service account access.
You can repeat these steps if you want to configure multiple limited users;
substitute a unique value for limited in each of the steps.

In the Admin console, define a new Admin role with the desired privileges,
assign it to the limited user and indicate whether it is for all Org Units or a specific Org Unit.

On your computer, perform these initial steps:

Make a subdirectory limited under the directory specified in gam.cfg config_dir

Create a new section at the end of your gam.cfg file.

text
[limited]
config_dir = limited

Copy client_secrets.json to the limited subdirectory

Select the limited section

text
gam select limited save

Limited Client access

Perform these steps to allow limited client access:

Configure todrive to allow uploading of files to the limited user's Google Drive.

text
gam config todrive_user [email protected] save

If it is not possible to allow the limited user any service account access (this is not common),
perform the following command so that the user can upload files with todrive using client access.

text
gam config todrive_clientaccess true save

Authorize the desired client access APIs; this will create oauth2.txt.
If it is not possible to allow the limited user any service account access,
login as the limited user; you must have assigned Admin API Privileges to the limited user
in the Admin console under Admin roles,

If the limited user will have service account access, login as a Google admin.

text
gam oauth create

No Client access

Perform these steps to allow no client access:

Configure todrive to allow uploading of files to the limited user's Google Drive.

text
gam config todrive_user [email protected] todrive_clientaccess false save

Configure for service account access only.

text
gam config user_service_account_access_only true save

Make a oauth2.txt file in the limited subdirectory with a single line as follows:

text
{}

This will prevent the limited user from having any client access.

Limited Service Account access

Perform these steps:

Create a a new service account in your project that will be used for the limited user;
this will create oauth2service.json.

text
gam add svcacct saname "gam-limited" sadisplayname "GAM Limited"

Authorize the desired APIs; this will update oauth2service.json with the list of authorized APIs.
Follow the directions to authorize the APIs; remember, you will login to the Admin console as a current
Google administrator.

text
gam user [email protected] update serviceaccount

If you disable a scope that was previously enabled, all of the remaining APIs will pass.
However, you should still go to the Admin console and update the client so that only the APIs
you've enabled are authorized.

todrive Service Account access

If the limited user is going to use todrive, authorize these APIs:

text
Drive API - todrive
Gmail API - Send Messages - including todrive
Sheets API - todrive

These APIs are only used to process todrive, they do not grant access to other user's files/sheets.
If the limited user is allowed access to other user's files/sheets, authorize these APIs:

text
Drive API (supports readonly)
Sheets API (supports readonly)

No Service Account access possible

If it is not possible to allow the limited user any service account access (this is not common),
perform these steps:

Make a oauth2service.json file in the limited subdirectory with a single line as follows:

text
{}

Test Client and Service Account access on your computer

Issue various Gam commands to verify that the limited user has only the desired access.
Repeat previous steps as required. Once testing is complete, perform the following step
to prevent the limited user from creating/updating oauth2.txt.

Edit the client_secrets.json file in the limited subdirectory to have a single line as follows:

text
{}

Install GAM on the limited users computer

Install GAM on the limited user's computer; it can be a different OS than your computer;
if asked by the installer, indicate:

  • that you do not want to set up a project
  • that you are performing an update

Make the necessary directories.

  • Make the GAM configuration directory; this can be different than on your computer.
  • Set the GAMCFGDIR environment variable to point to the GAM configuration directory.
  • Make a subdirectory gamcache under the GAM configuration directory.
  • Make a subdirectory limited under the GAM configuration directory.

Copy gam.cfg from your computer to the GAM configuration directory on the limited user's computer.
Edit gam.cfg

  • Remove any sections other than [DEFAULT] and [limited]
  • If the GAM configuration directory on the limited users computer is different than that on yours, update these values in the [DEFAULT] section:
    • cache_dir
    • config_dir
  • You may also want to update the GAM downloads directory:
    • drive_dir

Copy client_secrets.json, oauth2.txt and oauth2service.json from the limited subdirectory on your computer to the limited subdirectory on the limited user's computer.

Test Client and Service Account access on the non-administrator computer

Issue various Gam commands to verify that the limited user has only the desired access.
If you need to make changes, make them on your computer and then re-copy client_secrets.json, oauth2.txt and oauth2service.json to the limited user's computer.

Unselect limited section on your computer.

Once you have finished setting up authorizations for the limited user, you need to reset your gam.cfg to point to your default section or another section.

text
gam select default save
gam select <Section> save

Delete old versions of GAM from Configured Apps

text
In the Admin console, go to Security/Access and Data Control/API Controls/MANAGE APP ACCESS
Click Download list
Select Comma-separated values (.csv)
Click Download
Click Download CSV
The CSV file will be named: owl_apps.csv
Remove the rows of apps you want to keep.
Edit the column Access to UNCONFIGURED for those rows you want to remove.
Click Bulk update list
Click Attach CSV file
Locate owl_apps.csv
Click Upload
Click Upload
Click Confirm

File: wiki/Basic-Items.md

Basic Items

Primitives

text
/* Detailed source-code truncated for AI context efficiency. */

Items built from primitives

text
::= |<FalseValues>
 ::= <Number>[m|k|b]
<CIDRnetmask> ::= <Number>.<Number>.<Number>.<Number>/<Number>
<Year> ::= <Digit><Digit><Digit><Digit>
<Month> ::= <Digit><Digit>
<Day> ::= <Digit><Digit>
<Hour> ::= <Digit><Digit>
<Minute> ::= <Digit><Digit>
<Second> ::= <Digit><Digit>
<MilliSeconds> ::= <Digit><Digit><Digit>
<Date> ::=
        <Year>-<Month>-<Day> |
        (+|-)<Number>(d|w|y) |
        never|
        today
<DateTime> ::=
        <Year>-<Month>-<Day>(<Space>|T)<Hour>:<Minute> |
        (+|-)<Number>(m|h|d|w|y) |
        never|
        now|today
<Time> ::=
        <Year>-<Month>-<Day>(<Space>|T)<Hour>:<Minute>:<Second>[.<MilliSeconds>](Z|(+|-(<Hour>:<Minute>))) |
        (+|-)<Number>(m|h|d|w|y) |
        never|
        now|today
<RegularExpression> ::= <String>
        See: https://docs.python.org/3/library/re.html
<REMatchPattern> ::= <RegularExpression>
<RESearchPattern> ::= <RegularExpression>
<RESubstitution> ::= <String>>
 ::= <String>
        Must match this Python Regular Expression: [a-z][a-z0-9-]{4,28}[a-z0-9]
<ServiceAccountName> ::= <String>
        Must match this Python Regular Expression: [a-z][a-z0-9-]{4,28}[a-z0-9]
<SiteName> ::= [a-z,0-9,-]+
 ::= id:<String>|uid:<String>

Named items

text
/* Detailed source-code truncated for AI context efficiency. */

File: wiki/BNF-Syntax.md

Syntax

BNF Syntax

This Wiki describes the GAM7 command line syntax in modified BNF.

Skip the History section and start reading at Introduction.

Items on the command line are space separated, when an actual space character is required, it will be indicated by <Space>.
If an item contains spaces, it should be surrounded by ".

Metasyntactic symbols

text
[] optional item
() group items
* item may appear zero or more times
+ item may appear one or more times
| separates alternative items

Items

Collections

Python Regular Expressions

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#gam Browse gam catalog → #google Browse google catalog → #google-admin-sdk Browse google-admin-sdk catalog → #google-api Browse google-api catalog → #google-apps Browse google-apps catalog → #google-calendar Browse google-calendar catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →