TL;DR:
This is the first post in the series covering OAuth client IDs, one of the three credentials types used by Google APIs. (The other two credential types are API keys and service accounts (forthcoming), covered elsewhere.) Because the primary API family using OAuth client IDs are Google Workspace (GWS; formerly G Suite and Google Apps) APIs, this series also introduces readers on how to use them, starting with the Drive API, leading to more GWS API posts.
Introduction and motivation
Are you a developer but want to use Google APIs? Welcome to the blog dedicated to just that, in Python (and sometimes Node.js). Regardless of which APIs you want to use, I want to drop some "oil" on your experience to smoothen your onboarding friction. I especially like to cover content that's not in Google's documentation. Pick any topic, and I probably have you covered:
- Google Cloud/GCP (AI/ML, serverless)
- Google Workspace/GWS (Gmail, Drive, Docs, Sheets, etc.) and this series
- YouTube
- Maps
- Gemini
Workspace and its APIs
This series on Workspace and OAuth client IDs is great for those new to Google APIs, showing you how get started from scratch. Each API family differs from others, so while it would be great if the UX (user experience) was consistent across all APIs, they're not, and it's why I'm here.
Workspace is the collection of office productivity apps most of you are familiar with: Gmail, Google Drive, Calendar, Docs, Sheets, Slides, Forms, and others. Behind most of these well-known apps is a RESTful API. Why consider using these APIs?
- The 1st reason: you know the apps... you use Gmail, Drive, and Docs, so exploring them programmatically for automation is intriguing.
- The main reason: they're basically "free" up to certain limits (see sidebar below) and do not require a credit card (unlike most other Google APIs).
⚠️ ALERT: Cost: "free" up to certain limits
While many Google products & APIs are free to use, not all of them are. While not totally "free," use of GWS APIs is covered completely by your monthly "subscription," whether you're a paid subscriber or have a free consumer Google account (with or without Gmail, which is optional), meaning a $0USD monthly subscription rate.This "free" usage is not unlimited however... stay within the established quotas for each API. As expected, paid subscribers get more quota than free accounts. While not broadly published, you can get an idea of the limits on the Quotas page for Google Apps Script.
Authentication vs. Authorization
Regardless which Google APIs you use, there are two main requirements:
- Authentication ("authn") — typically login & password; using Google APIs requires a Google account
- Authorization ("authz") — an application needs permission to call an API & perform data access
A third item you should use is a "client library." While optional, their use is strongly recommended, and I'll cover this in the next post. Because both "authn" and "authz" represent long, similar words that start with, "auth," some think they're the same thing, but they're not.
The GWS API documentation has a detailed page covering all this, but I'll try to be more direct & concise.
Authn step: get a Google account and log into it
Authn refers to user identity, typically achieved with a login and password. More secure forms of authn include responding to a smartphone prompt or providing a biometric such as a fingerprint or retina scan. While a Google account is required to use Google APIs, it doesn't have to be a Gmail account; Google accounts can be based on an existing email address. Having a Gmail account is only convenient because it combines the two, giving you both a personal email and a Google account, in a single entity.
Another kind of Google account is a Workspace account. You get one when your company or school chooses Workspace as its office productivity suite. I don't recommend these types of accounts because it is very likely your school or company administrator has disabled developer projects because of billing or security concerns. So just stick with a Gmail or personal Google account.
Action item(s)
- Create a new Google account (or select an existing account).
Per my earlier remark, you can create an account with a Gmail address or without Gmail using your personal email address. Log into your new or existing account. You have now proven you are who you say you are and hve completed the authn step.
Authorization step: create developer project & credentials
Credentials give your code authorization to access a Google API. Google APIs support three credentials types. Which you use depends on who owns the data that an API accesses, as shown in the following table:
Credential type | Data accessed by API | Example API families |
---|---|---|
API key | Public data | Maps APIs |
OAuth client ID | Data owned by (human) users | GWS APIs |
Service account | Data owned by apps/projects | GCP APIs |
- API keys -- for APIs that access public data, e.g., looking for places on Google Maps, sending a picture to the GCP Vision API, searching YouTube for videos, sending a sentence to the GCP Natural Language API for analysis, and so on. Because all Maps APIs access public data, expect to only use API keys.
- OAuth client IDs -- for APIs that access data owned by (human) users. Your app needs a user's permission (in the form of "scopes") to access their documents on Drive, their messages in Gmail, videos in a user's YouTube playlists, and so on. Since Workspace data is almost always personal data, expect to use OAuth client IDs with all GWS APIs.
- Service accounts -- for APIs that access data owned by an app or project. For cloud-based apps, there's no human to prompt for permissions, plus the data isn't owned by humans anyway. Authorization is implicitly granted via service account and IAM (identity and access management roles) and public-private keypairs created with those specific permissions. As you can also guess, "cloud-based" primarily means GCP APIs.
Some Google APIs accept more than one type of credentials. For example, while you'd typically use service accounts with the GCP Cloud Vision API, sending an image (rather than reading a file from someone's Google Drive or a GCP project's Cloud Storage bucket) is considered "public data," so an API key works.
Another sample app I wrote uses OAuth client IDs to call the Vision API. The images are read from a user's Google Drive, so I was already using OAuth client IDs. Adding use of an API key or service account mixes credentials, making the code harder to read/understand. While API keys suffice, stricter credentials (OAuth client IDs or service accounts) are acceptable for the Vision API.
OPTIONAL: Complete experience via "codelab"
In the section below, I offlink several times to a tutorial (a "Google codelab") I wrote a few years ago introducing developers to coding with GWS APIs. Codelabs are self-paced, hands-on tutorials that lead you step-by-step in accomplishing a task and/or learning a Google API or API feature. Rather than regurgitating the exact same content in these posts, I'll point to specific sections to review or execute.
The codelab consolidates the content from these (three) posts and implements a Python script that isplays the first 100 files or folders in a user's Google Drive. We'll eventually end up there, but some of you may learn better/faster by doing an end-to-end, immersive project, in which case, feel free to do the entire codelab at http://g.co/codelabs/gsuite-apis-intro. (If interested, all Google codelabs can be accessed at http://g.co/codelabs.)
Now let's set up your project and allocate credentials for your app. If you're new to Google APIs, a project is the logical container for an application and its resources, and all API usage requires a project. Once you have a project, you need to create credentials for API access. Before executing the instructions below, review this page and this one in the official docs to get an idea of what you'll be doing because we're pretty much going to follow the steps outlined in those docs.
Action item(s)
- Go to the Developer Console ("DevConsole") at https://console.developers.google.com and sign into your Google account. See the sidebar below if you have multiple Google accounts.
- At the top of the DevConsole, create a new project (look for buttons labeled New Project or Create Project), or select an existing project. Specific instructions on project setup can be found in the codelab.
- Click on the Credentials tab in the left-nav to get to the credentials page listing all credentials for your project. Now click Create credentials at the top and select OAuth client ID. For Application type, select Desktop app. This and following steps are also detailed in the codelab as well as the docs pages listed at the end of the previous section.
- OAuth client IDs need a name, so take the default or create something meaningful like, "Google API demo".
- You may be prompted to create an OAuth consent screen; do so and select an External app. You only need to provide basic info like app name, email address, etc. Since we're only building a prototype, this info will only be exposed to you as the test user of your script. To learn more about this, see the OAuth consent screen documentation.
- After the client ID has been created, you'll be prompted to download a JSON credentials file. Rather than a super long default filename like,
client_secret_SOME-GIANT-HASH.googleusercontent.com
, save it with a shorter name, e.g.,client_secret.json
orclient_id.json
. With an active project and downloaded JSON credentials file, your authz tasks are complete.
TIP: More than one Google account?
If you have more than one Google account, select the avatar in the upper-right corner to confirm you're using the desired account. If not, select the correct one in the avatar dialog. When you have multiple Google accounts, an authenticated user ("auth user") number helps your browser differentiate between those users in any Google service URL. This number shows up in the URL in one of these two formats: 1)
...&authuser=N&...
or 2).../u/N/...
. In both cases,N
is the auth user number, starting at 0 (default) and incrementing for each account.As a convenience, you can add this HTTP field to most Google URLs to select which of your Google accounts to use. For example, use the following URL to access the DevConsole as auth user #2:
console.developers.google.com?authuser=2
.
Summary
Congrats! You've completed the first step in using Google APIs. Note there was no Python, Node.js, or any language-specific steps today; the process you completed is language-agnostic and API-agnostic, meaning you can use any Google API accepting OAuth client IDs as its authz mechanism, meaning an API that accesses user-owned data.
What's next?
In the next post, you will be taking more language- and API-dependent steps:
- Enable GWS APIs you wish to use
- Install client library for GWS APIs
For those who prefer more visual content, below is a video I made years ago covering much of what's in this post and giving you a preview of the next one. The video's screenshots are outdated now but the functionality has mostly remained the same. Until the next post!
NEXT POST: Part 2/3 on working with GWS APIs
References
Below are links related to the content in this post:
Code samples
- From this post (none)
- From all GWS posts
- From all posts
Hands-on "codelab" tutorials
- GWS API intro codelab (featuring Drive API)
- All Google codelabs
GWS APIs documentation
- All GWS APIs documentation
- GWS auth overview page
OAuth
- Google Developers OAuth client ID info
- OAuth consent screen & scope info
- OAuth2 documentation
- Google OAuth client ID support page
Other relevant content by the author
- Getting started with Google APIs: DevConsole intro post & video
- GWS/G Suite developer overview post & video (open to all but originally for students)
- OAuth client ID sample app using GCP (Storage, Vision) & GWS (Drive, Sheets APIs)
WESLEY CHUN, MSCS, is a Google Developer Expert (GDE) in Google Cloud (GCP) & Google Workspace (GWS), author of Prentice Hall's bestselling "Core Python" series, co-author of "Python Web Development with Django", and has written for Linux Journal & CNET. He runs CyberWeb specializing in GCP & GWS APIs and serverless platforms, Python & App Engine migrations, and Python training & engineering. Wesley was one of the original Yahoo!Mail engineers and spent 13+ years on various Google product teams, speaking on behalf of their APIs, producing sample apps, codelabs, and videos for serverless migration and GWS developers. He holds degrees in Computer Science, Mathematics, and Music from the University of California, is a Fellow of the Python Software Foundation, and loves to travel to meet developers worldwide at conferences, user group events, and universities. Follow he/him @wescpy & his technical blog. Find this content useful? Contact CyberWeb for professional services or buy him a coffee (or tea)!
Top comments (0)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.