Read a token and other credentials from a (non-REDCap) database or file

Source: R/retrieve-credential.R

These functions are not essential to calling the REDCap API, but instead are functions that help manage tokens securely.

retrieve_credential_local(
  path_credential,
  project_id,
  check_url            = TRUE,
  check_username       = FALSE,
  check_token_pattern  = TRUE
)
retrieve_credential_mssql(
  project_id,
  instance,
  dsn,
  channel    = NULL
)

Arguments

path_credential

The file path to the CSV containing the credentials. Required.
project_id

The ID assigned to the project withing REDCap. This allows the user to store tokens to multiple REDCap projects in one file. Required
check_url

A logical value indicates if the url in the credential file should be checked to have approximately the correct form. Defaults to TRUE.
check_username

A logical value indicates if the username in the credential file should be checked against the username returned by R. Defaults to FALSE.
check_token_pattern

A logical value indicates if the token in the credential file is a 32-character hexadecimal string. Defaults to FALSE.
instance

The casual name associated with the REDCap instance on campus. This allows one credential system to accommodate multiple instances on campus. Required
dsn

A DSN on the local machine that points to the desired MSSQL database. Required.
channel

An optional connection handle as returned by DBI::dbConnect(). See Details below. Optional.

Value

A list of the following elements:

  • redcap_uri: The URI of the REDCap Server.

  • username: Username.

  • project_id: The ID assigned to the project withing REDCap.

  • token: The token to pass to the REDCap server

  • comment: An optional string.

Details

If the database elements are created with the script provided in package's 'Security Database' vignette, the default values will work.

Note

Although we strongly encourage storing all the tokens on a central server (e.g., see the retrieve_credential_mssql() function and the "SecurityDatabase" vignette), there are times when this approach is not feasible and the token must be stored locally. Please contact us if your institution is using something other than SQL Server, and would like help adapting this approach to your infrastructure.

Author

Will Beasley

Examples

# ---- Local File Example ----------------------------
path <- system.file("misc/example.credentials", package = "REDCapR")
(p1  <- REDCapR::retrieve_credential_local(path, 153L))

#> $redcap_uri
#> [1] "https://bbmc.ouhsc.edu/redcap/api/"
#> 
#> $username
#> [1] "myusername"
#> 
#> $project_id
#> [1] 153
#> 
#> $token
#> [1] "9A81268476645C4E5F03428B8AC3AA7B"
#> 
#> $comment
#> [1] "simple static (read-only) test project"
#> 
(p2  <- REDCapR::retrieve_credential_local(path, 212L))

#> $redcap_uri
#> [1] "https://bbmc.ouhsc.edu/redcap/api/"
#> 
#> $username
#> [1] "myusername"
#> 
#> $project_id
#> [1] 212
#> 
#> $token
#> [1] "0434F0E9CF53ED0587847AB6E51DE762"
#> 
#> $comment
#> [1] "longitudinal (read-only) ARM test project"
#>