Introduction
BOO! Greetings from today's "Happy Halloween" topic: API keys. In many ways they're a "treat" because they're easy to learn and use. On the other hand, they can be "scary" because they're the most "vulnerable" of the various API security mechanisms that exist today. Bidding farewell to summer and settling into autumn, welcome everyone to the blog where I cover the use of Python and Google APIs, sometimes with some Node.js sprinkled in the cracks. It's aimed at developers who can be either novices or experts using Google APIs.
The goal is to help you get started from scratch, starting with the initial series introducing how to use OAuth client ID credentials and the Google Workspace (GWS) APIs, including the base requirements for using any Google APIs: authentication (also known as [a.k.a.] "authn": "you are who you say you are"), and authorization (a.k.a. "authz": "whether you/your app are authorized to access data/APIs").
The authn requirements are met by having a Google account while the authz requirements are met by having a developer project with appropriate application credentials. Credentials give your app(s) the authorization required to access Google APIs and more importantly, the data accessible from such APIs. Google APIs support three different credentials types where the one used 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 keys | Public data | Google Maps |
| OAuth client IDs | Data owned by (human) users | Google Workspace ("GWS") |
| Service accounts | Data owned by apps/projects | Google Cloud ("GCP") |
While the initial posts covered GWS APIs and OAuth client IDs, this post kicks off a new journey into Google APIs that use API keys as the primary supported credential type. As hinted in the table above, API keys are typically used by APIs that access public data. Seeking locations on Google Maps, searching for YouTube videos, and processing text or images with GCP AI/ML APIs, are all examples of accessing public data. Let's start with an API key primer.
API Keys
An API key is a unique string allowing applications to access services provided by APIs for which API keys are an accepted credential type. API keys ensure access only by legitimate/registered users and help track API usage on a per-user, per-app, or per-project basis. The service provider can then keep usage within established quotas and provide accurate billing for API usage/services.
Of all credentials types used with Google APIs, API keys are the most-straightforward to use and require the least amount of time to learn. That said, API keys are susceptible. If you accidentally leak your API key, e.g., embedded in plain text, distributed via archive (tar, zip, etc.), uploaded to GitHub, etc., that key can and will likely be exploited. As a result, API quotas can be maxed-out, resulting in API providers suspending infringing accounts and/or invalidating API keys.
The image below shows API keys are managed on the credentials page of the developer's console (DevConsole) in the top section (above OAuth client IDs covered in previous posts).
Creating API keys
Various Google APIs have documentation introducing API keys and showing you how to create them: GWS, GCP, and Maps. The key takeaway from these resources on creating API keys boils down to the following steps:
- Go to credentials page in DevConsole
- At the top, click + Create credentials >> API key (also see above image)
- [optional] Choose application or API restrictions on the newly-created API key
More on those restrictions in a moment. If you prefer to automate API key creation, there are two additional ways to create API keys, giving developers a total of three options:
- Create API keys in the DevConsole
- Create API keys using the
gcloudcommand-line interface (CLI) - Create API keys programmatically with the API Keys API.
For the latter, client libraries are available (for the API Keys API) in Python, Node.js, Java, and possibly others. Once API keys have been provisioned, they can be used immediately in API calls.
Restricting API keys
As mentioned earlier, API keys can be vulnerable, so during the creation process (or via API), you'll be prompted to protect it by reducing the number of possible attack vectors. More specifically, you can protect API keys with application or API restrictions.
API key application restrictions
Application restrictions limit an API key’s usage to HTTP referrers, meaning specific websites, IP addresses, or mobile applications. You can set one application restriction per key.
| Restriction | Description |
|---|---|
| None | No restrictions... all traffic can use API key |
| HTTP referrers | Restricts traffic from which domains, websites, and specific URLs that can use API key |
| IP addresses | Restricts traffic from specific IP addresses and subnets that can use API key |
| Android apps | Restricts traffic from specific Android apps that can use API key |
| iOS apps | Restricts traffic from specific iOS apps that can use API key |
For more details on application restrictions, see this section on the GCP API keys authn page.
API key API restrictions
API keys can also be constrained to being able to be used only to call specific APIs. Similar to application restrictions, API restrictions on API keys can be achieved on the DevConsole credentials page, via the gcloud CLI tool, or programmatically via the API Keys API.
For those using the DevConsole, the image below illustrates the section where you can restrict API keys on the credentials page. The top section is for the application restrictions described earlier, and the bottom section is where you can restrict API key usage accessing only the APIs you designate.
In that section, you have two choices: restrict or don't restrict the API key. To restrict the key, the pulldown menu allows you to select from all of the APIs you've enabled or that have been enabled on your project's behalf. Choose the desired APIs and save. The changes will take place shortly after.
To learn more about API restrictions, see this section on the GCP API keys authn page.
⚠️ WARNING: Keep API keys secure
Above, we covered a few ways to keep your API keys secure. Storing API keys in files (or hard-coding them for use in actual code or even assigning to environment variables) is for prototyping and learning purposes only. When going to production, put them in environment variables or in a secrets manager. Files likesettings.pyor.envcontaining API keys are susceptible. Under no circumstances should you upload files like those to any public or private repo, have sensitive data like that in TerraForm config files, add such files to Docker layers, etc., as once your API key leaks, everyone in the world can use it.If you're new to Google developer tools, API keys are one of the credentials types supported by Google APIs, and they're the only type supported by Maps APIs. Other credentials types include OAuth client IDs, mostly used by GWS APIs, and service accounts, mostly used by Google Cloud (GCP) APIs. While this post isn't dedicated to Google Maps APIs, the Maps team put together a great guide on API key best practices, so check it out!
Summary
API keys are the second credentials types accepted by Google APIs. They are fairly basic conceptually: a unique string identifying a Google developer project allowing access to certain Google APIs that (only) access public data. They can be created in the DevConsole, the gcloud CLI, or via the API Keys API.
API keys can be inadvertently leaked, resulting in quota overage and key invalidation, so developers should restrict their access to help protect their usage. Developers can place application restrictions on API keys, and they can also restrict which Google APIs can be called with an API key.
What's Next?
Now that you're familiar with API keys and how to create them, stay tuned for the next post where you'll see several examples of using them to access various Google APIs. Which APIs and what will they be used for? I dropped a hint above giving some examples of querying for public data, so expect to see some of that. In the meantime, have a spooky Halloween!
NEXT POST: Getting started using Google APIs: API Keys (Part 2)
References
- GWS credentials page section on API keys: https://developers.google.com/workspace/guides/create-credentials#api-key
- GCP API keys page: https://cloud.google.com/docs/authentication/api-keys
- Maps API keys page: https://developers.google.com/maps/documentation/javascript/get-api-key
- GCP API Keys API overview: https://cloud.google.com/api-keys/docs/overview
- GCP API Keys API Python client library: https://cloud.google.com/python/docs/reference/apikeys/latest
- GCP API Keys API Node.js client library: https://cloud.google.com/nodejs/docs/reference/apikeys/latest
- GCP API Keys API Java client library: https://cloud.google.com/java/docs/reference/google-cloud-apikeys/latest/overview
- Maps API keys best practices page: https://developers.google.com/maps/api-security-best-practices
- GCP API keys restrictions page: https://cloud.google.com/api-keys/docs/add-restrictions-api-keys
- DevConsole credentials page: https://console.cloud.google.com/apis/credentials
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)