Top level

gspread.oauth(scopes=['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'], flow=<function local_server_flow>, credentials_filename='/home/docs/.config/gspread/credentials.json', authorized_user_filename='/home/docs/.config/gspread/authorized_user.json')

Authenticate with OAuth Client ID.

By default this function will use the local server strategy and open the authorization URL in the user’s browser:

gc = gspread.oauth()

Another option is to run a console strategy. This way, the user is instructed to open the authorization URL in their browser. Once the authorization is complete, the user must then copy & paste the authorization code into the application:

gc = gspread.oauth(flow=gspread.auth.console_flow)

scopes parameter defaults to read/write scope available in gspread.auth.DEFAULT_SCOPES. It’s read/write for Sheets and Drive API:

DEFAULT_SCOPES =[
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/drive'
]

You can also use gspread.auth.READONLY_SCOPES for read only access. Obviously any method of gspread that updates a spreadsheet will not work in this case:

gc = gspread.oauth(scopes=gspread.auth.READONLY_SCOPES)

sh = gc.open("A spreadsheet")
sh.sheet1.update('A1', '42')   # <-- this will not work

If you’re storing your user credentials in a place other than the default, you may provide a path to that file like so:

gc = gspread.oauth(
    credentials_filename='/alternative/path/credentials.json',
    authorized_user_filename='/alternative/path/authorized_user.json',
)
Parameters:
  • scopes (list) – The scopes used to obtain authorization.
  • flow (function) – OAuth flow to use for authentication. Defaults to local_server_flow()
  • credentials_filename (str) –

    Filepath (including name) pointing to a credentials .json file. Defaults to DEFAULT_CREDENTIALS_FILENAME:

    • %APPDATA%gspreadcredentials.json on Windows
    • ~/.config/gspread/credentials.json everywhere else
  • authorized_user_filename (str) –

    Filepath (including name) pointing to an authorized user .json file. Defaults to DEFAULT_AUTHORIZED_USER_FILENAME:

    • %APPDATA%gspreadauthorized_user.json on Windows
    • ~/.config/gspread/authorized_user.json everywhere else
Return type:

gspread.Client
gspread.service_account(filename='/home/docs/.config/gspread/service_account.json', scopes=['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'])

Authenticate using a service account.

scopes parameter defaults to read/write scope available in gspread.auth.DEFAULT_SCOPES. It’s read/write for Sheets and Drive API:

DEFAULT_SCOPES =[
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/drive'
]

You can also use gspread.auth.READONLY_SCOPES for read only access. Obviously any method of gspread that updates a spreadsheet will not work in this case.

Parameters:
  • filename (str) – The path to the service account json file.
  • scopes (list) – The scopes used to obtain authorization.
Return type:

gspread.Client
gspread.authorize(credentials, client_class=<class 'gspread.client.Client'>)

Login to Google API using OAuth2 credentials. This is a shortcut function which instantiates client_class. By default gspread.Client is used.

Returns:client_class instance.