Appendix C — Getting API Tokens for Other Repositories

Metacheck can read files directly from several online repositories: the Open Science Framework (OSF), Zenodo, Dataverse, Dryad, Figshare, 4TU.ResearchData, and GitLab, among others. For most of these, an access token is optional, and only raises how many requests you may make per hour or gives you access to your own private material. For one of them, Dryad, a token is required even to download files from a fully public dataset.

The Downloading an OSF Account and Uploading Files to Zenodo chapters already explain, with screenshots, how to create and store a token for those two services. This chapter does the same for the remaining repositories: Dataverse, Dryad, Figshare, 4TU.ResearchData, GitLab, GitHub and ResearchBox, and for OpenAlex, which some modules use to look up references. The last section shows how to check which keys Metacheck finds.

An access token is a long string of letters and numbers that proves to a website that a program is acting on your behalf. It works like a password that you give to one specific program, and that you can revoke without changing your real password.

Every token in this chapter is stored the same way: in a file called .Renviron, which R reads when it starts. Open it with:

usethis::edit_r_environ()

Add the line for the service you need, using the exact name shown below, save the file, and restart R (Ctrl+Shift+F10 in RStudio). The restart matters: .Renviron is only read when R starts, so a token added without restarting will not be found.

Using a token for one session only

Every function below that reads a token (dataverse_pat(), dryad_pat(), figshare_pat(), researchdata4tu_pat(), gitlab_pat(), github_pat(), rbox_token(), openalex_key()) also sets it when you pass a value as an argument, for the rest of the current session only:

figshare_pat("paste-your-token-here")

This is forgotten when you close R. Storing the token in .Renviron instead means you do not have to repeat this every time you start R.

C.1 Dataverse

Dataverse is not a single website but open-source software that many independent organisations each run on their own address — Harvard Dataverse, DataverseNL, and the DANS Data Stations are three examples. Because of this, each Dataverse installation issues its own token, and a token from one installation does nothing on another.

Go to the installation’s own site and log in. Click your account name in the navigation bar, and choose API Token from the dropdown menu. This opens a page with a Create Token button (or Recreate Token, if you already have one). For Harvard Dataverse, for example, this account menu is reached from https://dataverse.harvard.edu.

Because the token is tied to one installation, storing it also requires naming the installation. dataverse_pat() takes a host, and looks for the token under a name made from that host: DATAVERSE_PAT_ followed by the host in capital letters, with every . (and any other character that is not a letter or digit) replaced by _. Store it under that name, and pass the host when you check it:

DATAVERSE_PAT_DATAVERSE_HARVARD_EDU="paste-your-token-here"

dataverse_pat(host = "dataverse.harvard.edu")

If you work with more than one Dataverse installation, add one line per installation, each named after its own host in the same way (for example DATAVERSE_PAT_DATAVERSE_NL for dataverse.nl), and call dataverse_pat() with the matching host each time.

C.2 Dryad

Dryad is a single service, at https://datadryad.org. Unlike every other repository in this chapter, a token is not optional: Dryad answers file-download requests with an error unless a token is present, even for a dataset anyone can see on the website. Without a token, you can still see what a dataset contains — Dryad’s listing of a dataset’s files works without one — but you cannot retrieve any of the files themselves.

C.2.1 Creating a Dryad API account

Log in at https://datadryad.org, go to My account, and click Create a Dryad API account. This gives you an API account ID, a secret, and an initial access token.

Every Dryad token expires after 10 hours

Unlike the other tokens in this chapter, a Dryad access token – whether it is the initial one you were given, or one you obtain later – is only valid for 10 hours. After that it must be replaced with a new one. There is no way around this with a single stored token, which is why Dryad also gives you an account ID and secret: those do not expire, and can be exchanged for a fresh token automatically.

C.2.2 Using the initial token directly

For a single session, you can store the initial access token the same way as any other token in this chapter:

DRYAD_PAT="paste-your-token-here"

Check it:

dryad_pat()

Once 10 hours have passed, this stops working, and you must sign in again, obtain a new token, and update .Renviron.

C.2.3 Using the account ID and secret, for long-running work

Rather than storing a token that expires, you can give Metacheck your Dryad API account ID and secret. Metacheck then exchanges them for an access token itself, and repeats the exchange automatically whenever the token is about to expire, for as long as the account ID and secret remain valid:

dryad_auth(
  client_id = "paste-your-api-account-id-here",
  client_secret = "paste-your-secret-here"
)

This sets the account ID and secret for the current session only. To have them read every time R starts, store them in .Renviron instead, as two lines; Metacheck then uses them automatically, without a call to dryad_auth():

DRYAD_CLIENT_ID="paste-your-api-account-id-here"
DRYAD_CLIENT_SECRET="paste-your-secret-here"

When an account ID and secret are set, they are used instead of DRYAD_PAT. Use whichever of dryad_pat() or dryad_auth() suits the job: dryad_pat() for a quick session under 10 hours; dryad_auth() for a script that will keep running past that, such as building a large corpus of downloaded datasets.

C.3 Figshare

Figshare is a single service at https://figshare.com, with several institutions — including the University of Leicester and DTU Data — running their own branded address on the same underlying service. A token is not needed for reading public articles, and does not raise any request limit there; it is required to read a private article.

Create a token at https://figshare.com/account/applications. Log in, open that page, and create a new personal token there.

Store it as:

FIGSHARE_PAT="paste-your-token-here"

Check it:

figshare_pat()

C.4 4TU.ResearchData

4TU.ResearchData, at https://data.4tu.nl, runs Djehuty, which is a documented copy of Figshare’s own software. Because of this, its functions in Metacheck reuse Figshare’s own code. This does not mean a Figshare.com token works here: 4TU.ResearchData is a separate organisation with its own accounts, so it issues its own tokens, stored separately from figshare_pat().

Log in at https://data.4tu.nl, go to your Applications, and click Create Personal Token. Give it a short description, such as metacheck, and save; the token is shown once, so copy it before leaving the page.

Store it as:

RESEARCHDATA4TU_PAT="paste-your-token-here"

Check it:

researchdata4tu_pat()

C.5 GitLab

This covers gitlab.com itself, not a self-hosted GitLab instance run by another organisation. A token is optional for listing or downloading a public project, where it only raises GitLab’s unauthenticated rate limit; it is required for a private project.

Log in at https://gitlab.com, open your avatar menu in the top right, choose Edit profile, and select Access Tokens in the left sidebar (or go directly to https://gitlab.com/-/user_settings/personal_access_tokens). Give the token a name and an expiry date, tick the read_repository scope, which covers reading a project’s files over the repository files API, and click Create personal access token.

Store it as:

GITLAB_PAT="paste-your-token-here"

Check it:

gitlab_pat()

C.6 GitHub

A token is optional: public repositories can be read without one, but GitHub then allows only 60 requests per hour, and a token raises this to 5,000. A fine-grained token that may only read public repositories gives Metacheck nothing that is not public anyway. Make one at https://github.com/settings/personal-access-tokens/new, choose Public repositories under Repository access, and add no permissions.

Store it as:

GITHUB_PAT="paste-your-token-here"

Check it:

github_pat()

Without GITHUB_PAT, github_pat() finds a token the way git does, in git’s own store of passwords.

C.7 ResearchBox

ResearchBox’s API needs a personal key, which you make at https://researchbox.org/api. Without a key, Metacheck reads a box’s web page instead, and the search and file-list functions of the API are not available. The key is also used for AsPredicted: ResearchBox’s API serves AsPredicted’s public preregistrations, which the prereg_check module reads. Without a key, they are read from AsPredicted’s web pages, and AsPredicted asks for a captcha after several pages, after which no more are read.

Store it as:

RESEARCHBOX_API_KEY="paste-your-key-here"

Check it:

rbox_token()

C.8 OpenAlex

OpenAlex works without a key, with a budget of US$0.10 per day: about 1,000 searches, while looking up a work by its DOI or OpenAlex ID is free. A free key raises the budget to US$1 per day. Sign up at https://openalex.org/signup and copy the key from https://openalex.org/settings/api-key.

Store it as:

OPENALEX_API_KEY="paste-your-key-here"

Check it:

openalex_key()

C.9 Checking which keys are set

api_key_status() lists the services for which Metacheck uses a key (GitHub, OSF, Dryad, ResearchBox, GitLab and OpenAlex), whether a key is set, and whether a key was recently refused or reached its limit, with the address where you can make one:

api_key_status()[, c("service", "key", "problem")]

When a service refuses a key, or the key reaches its limit, Metacheck records this in a file in its state folder, in tools::R_user_dir("metacheck", "data"). Every R session of the same user on the computer reads that file, so another session knows about the problem before it sends a request.

C.10 When something goes wrong

A *_pat() function returns "". R cannot find your token. Restart R, then check .Renviron has the line with quotation marks and a blank line at the end of the file, exactly as described in the Downloading an OSF Account chapter — the same cause and the same fix apply to every token in this chapter.

Dryad downloads fail with files listed but none retrieved. This is expected without a token: Dryad allows listing a public dataset’s files without one, but refuses to send the file contents. Set DRYAD_PAT, or use dryad_auth(), and try again.

A Dryad token stops working after it used to work. Every Dryad token expires after 10 hours, including the initial one from account creation. If you are storing it with DRYAD_PAT, sign in again and get a new one. Switch to dryad_auth() with your account ID and secret so this stops happening.

A Dataverse token works on one installation but not another. This is expected: each Dataverse installation issues and checks its own tokens. Create a separate token on the installation that is failing, and pass its host to dataverse_pat().

A 4TU.ResearchData request fails even though the Figshare token is set. 4TU.ResearchData does not accept a Figshare.com token. Create a separate token on data.4tu.nl and store it as RESEARCHDATA4TU_PAT.