Getting started using Google APIs: Workspace & OAuth client IDs (1/3)
Tags: googlecloud, googleapi, googleappsscript, gmail
Published: 2023-05-01 17:29:13

<!-- Getting started using Google APIs: Workspace (Part 1/3) -->

## Introduction

Are you a developer but a complete beginner using Google APIs? This series is for you because I'm 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 completely consistent across all APIs, this isn't the case, so my goal is to help developers understand how their use differs between product families. As mentioned in the [previous post](/wescpy/coding-python-and-google-with-wescpy-3bag), I'm starting with the Google Workspace (formerly called _G Suite_ and _Google Apps_) APIs.

Google Workspace ("GWS") refers to the collection of: Gmail, Google Drive, Calendar, Docs, Sheets, Slides, Forms, plus others. Behind each of these well-known apps is a RESTful API. Why GWS APIs first? The main reason is they're completely free (up to certain limits) and **do not require a credit card**. Don't worry though... we'll get to other Google APIs soon thereafter, including: Cloud ("GCP"), Google Maps, YouTube, Firebase, etc., and more interesting, demo apps using APIs from different product families.

Regardless of which Google APIs you use, there are **two** main requirements:

1. **Authentication** — typically login &amp; password; using Google APIs requires a Google account
1. **Authorization** — an application needs permission to call an API &amp; 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 topic in the next post. Authentication and authorization are commonly abbreviated as "authn" and "authz", respectively. Because both are long, similar words that start with, "auth," some think they're the same thing, but alas, they're not. Check out [this page](https://developers.google.com/workspace/guides/auth-overview) in the official docs to help differentiate. I'll do the same below as well as guide you to creating the required resources.

## Authentication ("authn") — get a Google account

![authentication](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6jown9yjz507f2lh0qmp.jpg)
<figcaption>Authentication: proving you are who you say you are</figcaption>

<br>
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](https://gsuite.google.com) 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)

1. Create a new Google account (or select an existing account). Per my earlier remark, you can [create an account **with** a Gmail address](https://accounts.google.com/SignUp) _or_ [**without** Gmail](https://accounts.google.com/SignUpWithoutGmail) using your personal email address. Once you're logged into your new or existing Google account, you're done with authn.


## Authorization ("authz") — create a Google developer project and relevant credentials

![authorization meme image](https://img.memegenerator.net/instances/81080343.jpg)
<figcaption>Authorization: You may be authenticated, but do you have API/data access?</figcaption>

<br>
Credentials give your app the 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 Google 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
<figcaption>Required credential type determined by API data "owner"</figcaption>

<p>&nbsp;</p>
<br clear=all>

1. **API keys** — used 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, and so on. Because all _Maps APIs_ access public data, expect to only use API keys.
1. **OAuth client IDs** — used for _APIs that access data owned by (human) users_. Your app needs a user's permission 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 _GWS APIs_.
1. **Service accounts** — used 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 public/private keypairs created with specific permissions. As you can also guess, this means _GCP APIs_ typically require service accounts.

As mentioned in the [previous post](/wescpy/coding-python-and-google-with-wescpy-3bag), I'm starting with GWS APIs first, meaning using _OAuth client IDs_. Future posts will cover Google APIs that use either _API keys_ or _service accounts_. From the above, while it may seem APIs only accept one type of credentials, note that some Google APIs accept more than one type.

For example, while the [Cloud Vision API](http://cloud.google.com/vision) typically expects service accounts, it may also work with API keys or OAuth client IDs. I created a [sample app featuring the Vision API where it used OAuth client IDs for authz](http://goo.gle/3nPxmlc) — my justification being that the app also uses the Drive and Sheets APIs. It's already tricky enough using multiple Google APIs much less using multiple credentials types too.


> #### 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](https://support.google.com/cloud/answer/6158849) and [this one](https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid) 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)

![Google DevConsole](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0llocup4z90sgelp970r.png)
<figcaption>Google developer console ("DevConsole")</figcaption>

<br>
1. 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.
1. 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](https://codelabs.developers.google.com/codelabs/gsuite-apis-intro/#5).
1.  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](https://codelabs.developers.google.com/codelabs/gsuite-apis-intro/#6) as well as the docs pages listed at the end of the previous section.
1. OAuth client IDs need a name, so take the default or create something meaningful like, "Google API demo".
1. 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](https://developers.google.com/workspace/guides/configure-oauth-consent).
1. 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` or `client_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`.


## What's next?

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. In the next post, you _will_ be taking more language- and API-dependent steps:

1. Enable GWS APIs you wish to use
1. 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!

{% youtube DYAwYxVs2TI %}
<figcaption>[VIDEO] Creating new apps using Google APIs: DevConsole intro</figcaption>

<br clear=all>
NEXT POST: [Part 2/3 on working with GWS APIs](https://dev.to/wescpy/getting-started-using-google-apis-workspace-23-3ch8)

---
<small>
**WESLEY CHUN**, MSCS, is a [Google Developer Expert](https://developers.google.com/experts) (GDE) in Google Cloud (GCP) &amp; Google Workspace (GWS), author of Prentice Hall's bestselling ["Core Python"](https://corepython.com) series, co-author of ["Python Web Development with Django"](https://withdjango.com), and has written for Linux Journal & CNET. He runs [CyberWeb](https://cyberwebconsulting.com) specializing in GCP & GWS APIs and serverless platforms, [Python & App Engine migrations](https://appenginemigration.com), 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](http://bit.ly/3xk2Swi) and [GWS developers](http://goo.gl/JpBQ40). 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](https://twitter.com/wescpy) & his [technical blog](https://dev.to/wescpy). Find this content useful? [Contact CyberWeb](https://forms.gle/bQiDMiGyGrrwv5sy5) if you may need help or [buy him a coffee (or tea)](http://buymeacoffee.com/wescpy)!
</small>