Top level

gspread.oauth(scopes: ~typing.Iterable[str] = ['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'], flow: ~gspread.auth.FlowCallable = <function local_server_flow>, credentials_filename: str | ~pathlib.Path = PosixPath('/home/docs/.config/gspread/credentials.json'), authorized_user_filename: str | ~pathlib.Path = PosixPath('/home/docs/.config/gspread/authorized_user.json'), http_client: ~typing.Type[~gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>) → Client

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

  • http_client (gspread.HTTPClient) – A factory function that returns a client class. Defaults to gspread.http_client.HTTPClient (but could also use gspread.http_client.BackOffHTTPClient to avoid rate limiting)

Return type:

gspread.client.Client

gspread.service_account(filename: ~pathlib.Path | str = PosixPath('/home/docs/.config/gspread/service_account.json'), scopes: ~typing.Iterable[str] = ['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'], http_client: ~typing.Type[~gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>) → Client

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.

  • http_client (gspread.HTTPClientType) – A factory function that returns a client class. Defaults to gspread.HTTPClient (but could also use gspread.BackOffHTTPClient to avoid rate limiting)

Return type:

gspread.client.Client

gspread.authorize(credentials: ~google.auth.credentials.Credentials, http_client: ~typing.Type[~gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>, session: ~requests.Session | None = None) → Client

Login to Google API using OAuth2 credentials. This is a shortcut/helper function which instantiates a client using http_client. By default gspread.HTTPClient is used (but could also use gspread.BackOffHTTPClient to avoid rate limiting).

It can take an additional requests.Session object in order to provide you own session object.

Note

When providing your own requests.Session object, use the value None as credentials.

Returns:

An instance of the class produced by http_client.

Return type:

gspread.client.Client