# 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

- https://www.dartistics.com/renviron.html