The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Tokens

REDCap API tokens

REDCap API tokens are equivalent to your username and password. They should never be shared with anyone. Ideally, they should never be directly written in an R script, especially if you plan on sharing it in the future. Never commit a file containing your token on git or GitHub because this will forever be in the history. If there is ever any doubt in your mind you should quickly regenerate your token on the REDCap website. If you are working on a real REDCap project it’s good practice to regenerate your token periodically, such as once a week, just to be safe.

Precisely because tokens are sensitive, REDCapSync is designed to only reference the name of your token, such as “REDCAPSYNC_FIRST_PROJECT”. If REDCapSync ever wants to use the token to make an API call to REDCap, it will check Sys.getenv("REDCAPSYNC_FIRST_PROJECT"). By default are token names start with “REDCAPSYNC_”, followed by the project_name you chose in setup_project(). Below demonstrates how to set and check your tokens…

1. Setting Your Token using User Environment Variables (preferred)

You may find want to reuse a token, and you may have several projects, so a convenient way to store the tokens in a separate location. One way to do this is your personal .Renviron file. Again, you should check always confirm the location of this file and make sure it’s not a part of any cloud storage or git or GitHub. You can use usethis::edit_r_environ() to semi-permanently save your token. Each time you launch an R session this file will run and your token will be visible to you if specifically called with Sys.getenv("REDCAPSYNC_FIRST_PROJECT").

  1. Open the .Renviron file with usethis::edit_r_environ()
  2. Add the token like this… REDCAPSYNC_FIRST_PROJECT = "faKeTokeN"
  3. Save the file and Close
  4. Restart R Session (Session tab or .rs.restartR()).
  5. Confirm with Sys.getenv("REDCAPSYNC_FIRST_PROJECT")
#Install usethis if you don't have it.
#install.packages("usethis") 
usethis::edit_r_environ()
# Now save your token.... (without the comment symbol '#')
# REDCAPSYNC_FIRST_PROJECT = "faKeTokeN"
# Save the file and Close
# Restart R Session (session tab)
# .rs.restartR() # this will also restart R session for you.
Sys.getenv("REDCAPSYNC_FIRST_PROJECT") # now should contain your token

The only reference to your token that is ever made or saved in REDCapSync is with its name. For example, any REDCap project object will have the token name at project$token_name. In the future, we may set our token in a different way.

2. Setting Your Token using keyring package

By default REDCapSync will use keyring = NULL, which is your OS system default and is typically unlocked by default while you are logged in.

project <- load_project("TEST_CLASSIC")

project$set_keyring_token() # now enter token in pop-up
# internally the package checks ...
#1. Sys.getenv()
token <- Sys.getenv(project$.internal$token_name)
#2. followed by keyring
token <- keyring::key_get(service = config$keyring.service(),
                          username = project$project_name,
                          keyring = config$keyring())
# you could set with the following; not preferred because token in script
# if you do this set in securely in file that no one can ever see; never github!
keyring::key_set_with_value(service = config$keyring.service(),
                            username = project$project_name,
                            password = "VeryNOTsecureWayToSetYourTOKEN",
                            keyring = config$keyring())

You can change default configuration to give you more fine-tuning of keyrings using configuration settings…

options(redcapsync.config.keyring = "REDCapSync")
# with this kind of method you could define multiple tokens in a private/secret
# .R file which can be sourced to set all tokens in akeyring. Can also be 
# locked and unlocked (see keyring webstite for details)

3. Setting Your Token for One Session

You can set manually with base R. Unless you specifically set the token Sys.getenv("REDCAPSYNC_FIRST_PROJECT") will be blank.

# Set your token manually
# again having this in a script is not advised but possible
Sys.setenv(REDCAPSYNC_FIRST_PROJECT="a_FaKe_TOkEn") 

# Get your token
Sys.getenv("REDCAPSYNC_FIRST_PROJECT")
#>[1] "a_FaKe_TOkEn"

Now the token is set for this R session only. If you restarted R, it would be blank again.

Testing Your Token (optional)

If you are ever having any issues with your token, you can test your project object with project$test_token().

project <- load_project("TEST_CLASSIC") # replace project name with yours

project$test_token()

Additional Resources

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.