Top level

gspread.oauth(scopes: ~typing.Iterable[str] = ['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'], flow: ~typing.Callable[[...], ~google.auth.credentials.Credentials] = <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'>) → 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).

Returns:

An instance of the class produced by http_client.

Return type:

gspread.client.Client