Managing Secrets

To use an application programming interface, or API, you will need an API key.

What is an API Key?

An API key is a unique code used to identify and authenticate a user or application when interacting with an API.

API keys are generally a string of alphanumeric characters, and look something like this:

zaCELgL0imfnc8mVLWwsAawjYr4RxAf50DDqtlx

API keys are a security measure to make sure you, or your application, are who you say you are.

Think of it like an ID card. You wouldn’t want to leave your ID card laying around, and you don’t want to leave your API key laying around either. Anyone could just pick it up and pretend they are you!

Since API keys are plain text, if API keys are stored in your code, when you share your code, such as on GitHub, they will be readable by everyone that has access to that GitHub repository.

Consider this R code below that retrieves data from the US decennial census:

library(tidycensus)
library(tidyverse)

census_api_key("zaCELgL0imfnc8mVLWwsAawjYr4RxAf50DDqtl")

# Retrieve median age by sex (P13_001N) by state
age_2020 <- get_decennial(geography = "state", 
                       variables = "P13_001N", 
                       year = 2020,
                       sumfile = "dhc")

The API key is stored in plain-text as a variable. If this code were shared, anyone would be able to use the API key.

How do we protect API keys?

We need some way of using an API key in our code without making it shareable.

There are a number of ways we can accomplish this, but this dispatch will focus on one way that is both platform agnostic (works on Mac, Windows, and Linux) and works in most programming languages; environment variables.

Environment Variables

A variable allows us to store information, and an environment is the system we execute our code on. Environment variables allow us to store information specific to a system in variables. Environment variables are not stored within our codebase, but are instead stored in a system specific configuration file.

We can use the environment variables configuration file to store our API key, and reference the configuration file in our code in order to load the API key.

Environment Variables in R

In R, environment variables can be stored in a text file with name-value pairs. Create a file in your home directory by running:

file.edit("~/.Renviron")

Using the API key listed earlier, we would declare an environment variable in our .Renviron file:

API_KEY = "zaCELgL0imfnc8mVLWwsAawjYr4RxAf50DDqtlx"

Now we can update our code to retrieve our API environment variable:

library(tidycensus)
library(tidyverse)

# Retrieve API key from .Renviron file
api_key <- Sys.getenv("API_KEY")
census_api_key(api_key)

# Retrieve median age by sex (P13_001N) by state
age_2020 <- get_decennial(geography = "state", 
                       variables = "P13_001N", 
                       year = 2020,
                       sumfile = "dhc")

Our API key is now secret, and will not be shared with our codebase!