Skip to contents

Storing your ServCat API key

Source: vignettes/storing_api_key.qmd

Some servcat functions may require a ServCat API key. The recommended way to provide this key is to store it as an environment variable instead of typing it directly into your scripts.

This keeps your key out of your project files, reduces the chance of accidentally committing it to GitHub, and lets servcat find the key automatically when needed.

Why use an environment variable?

Avoid writing API keys directly in scripts like this:

api_key <- "your-api-key-here"

That approach is risky because the key can easily be saved in your R history, shared in a script, or committed to a public repository.

Instead, store the key outside your project code and read it when needed:

Sys.getenv("SERVCAT_API_KEY")

Store your key in .Renviron

The easiest persistent option is to save your key in your user-level .Renviron file.

Open your .Renviron file with:

usethis::edit_r_environ()

If you do not have the usethis package installed, install it first:

install.packages("usethis")

Then add a line like this to the file:

SERVCAT_API_KEY=your-api-key-here

Do not put quotation marks around the key unless the key itself contains characters that require quoting.

After saving the file, restart R so the new environment variable is loaded.

Check that R can find your key

After restarting R, check that the environment variable is available:

Sys.getenv("SERVCAT_API_KEY")

If R returns your key, it is available for use.

To avoid printing the full key, you can check whether it is set:

nzchar(Sys.getenv("SERVCAT_API_KEY"))

A result of TRUE means R found a non-empty value.

Use the key with servcat

Once the key is stored, servcat can read it from your environment. For example:

library(servcat)

refs <- get_references(c(140411, 140412))
refs

If your session cannot find the key, restart R and check:

Sys.getenv("SERVCAT_API_KEY")

Temporary API key setup

For a single R session, you can set the key with:

Sys.setenv(SERVCAT_API_KEY = "your-api-key-here")

This only lasts for the current R session. When you restart R, the value will be gone.

For routine use, prefer storing the key in .Renviron.

Troubleshooting

Sys.getenv("SERVCAT_API_KEY") returns an empty string

R could not find the variable. Check that:

  • the variable name is spelled exactly as SERVCAT_API_KEY
  • the line was saved in your user-level .Renviron
  • R was restarted after editing .Renviron
  • there are no extra spaces around the variable name

The .Renviron line should look like this:

SERVCAT_API_KEY=your-api-key-here

not this:

SERVCAT_API_KEY = your-api-key-here

The key works in one project but not another

The key may have been set only for a single R session or only for one project. For regular use across projects, store it in your user-level .Renviron file with:

usethis::edit_r_environ()

Summary

Use this pattern for persistent local setup:

SERVCAT_API_KEY=your-api-key-here

Then restart R and confirm that the key is available:

nzchar(Sys.getenv("SERVCAT_API_KEY"))

After that, servcat functions can use the key without requiring you to place it directly in your scripts.