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.

Managing Authentication and Configuration in hawkinR v2.0

Introduction

The 2.0 release of hawkinR introduces a secure, profile-based authentication system built on the S7 object-oriented framework. By leveraging your computer’s native password manager and formal S7 classes, you can now manage multiple team tokens securely without ever hardcoding sensitive secrets into your R scripts.

1. Local Setup (Development)

On your local machine, hawkinR uses your computer’s built-in password manager (Keychain on Mac, Credential Manager on Windows) to encrypt your keys. You should never have to handle the keyring package directly; hawkinR provides helper functions to manage this for you.

Storing your Credentials

You only need to do this once per machine or whenever you receive a new token from your Org Admin.

library(hawkinR)

# This will open a secure popup window asking for your Refresh Token.
# We recommend naming your primary key "default".
hd_auth_store(profile = "default")

Connecting

Once stored, connecting is a single line of code. hawkinR retrieves your key, exchanges it for a temporary access token, and sets up your “Active Connection” in the background.

# Connects using the 'default' profile 
hd_connect()

# Fetch data immediately - the connection is handled implicitly
trials <- get_tests()

2. Managing Multiple Profiles (Teams)

If you have “Team Scoped Tokens” for different groups, or if you are a consultant managing multiple organizations, you can save them under unique profile names.

Setup Multiple Keys

Code snippet

hd_auth_store(profile = "mens_soccer") 
hd_auth_store(profile = "womens_soccer")

Switching Contexts

To switch which data you are pulling, simply reconnect with the desired profile:

# Switch to the Men's team context 
hd_connect(profile = "mens_soccer") 
men_data <- get_tests()

# Switch to the Women's team context
hd_connect(profile = "womens_soccer") 
women_data <- get_tests()

3. Production & Cloud Deployment

When deploying to a server (like ShinyApps.io, Posit Connect, or a Docker container), the keyring is typically unavailable. In these “headless” environments, hawkinR looks for Environment Variables.

Step A: Configure the Server

Add a variable to your server’s environment or your .Renviron file formatted as HAWKIN_KEY_{PROFILE_NAME}.

# Example .Renviron entries 
HAWKIN_KEY_DEFAULT="your_secret_refresh_token_here" 
HAWKIN_KEY_MENS_SOCCER="another_secret_token_here"

Step B: Connect in Production Mode

Tell hd_connect to bypass the keychain and look for environment variables.

# This tells the package to use System Environment Variables 
hd_connect(environment = "production")

# The rest of your code remains identical
df <- get_tests()

4. Advanced: Explicit Connection Objects

While get_tests() usually finds the “Active Connection” automatically, power users can manage connection objects manually using S7 syntax.

# Create specific session objects 
conn_a <- hd_connect(profile = "org_a") 
conn_b <- hd_connect(profile = "org_b")

# Pass the connection as the first argument to any 'get' function

data_a <- get_tests(conn_a, from = "2024-01-01") 
data_b <- get_tests(conn_b, from = "2024-01-01")

Summary of Commands

Function	Purpose
hd_auth_store(“name”)	Saves a key to your computer’s secure vault.
hd_auth_reset(“name”)	Deletes a key from your computer’s vault.
hd_connect(profile = “name”)	Initializes the session and sets it as “Active”.
get_tests(…)	Fetches data using the current Active connection.

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.