Authentication and Project Setup

Overview

ukbflow interacts with the UK Biobank Research Analysis Platform (RAP) via the DNAnexus dx toolkit. Authentication is required to access your UKB project, submit jobs, and retrieve results.

Two working modes are supported:

• Local → RAP: Run R locally, authenticate with a DNAnexus API token, and interact with RAP remotely.
• RAP → RAP: Run R inside the RAP cloud environment (e.g., RStudio on DNAnexus), where authentication is handled automatically by the platform.

Obtaining an API Token

1. Log in to the DNAnexus platform
2. Go to Account Settings > API Tokens
3. Click New Token, set an appropriate expiry, and copy the token

Keep your token private. Treat it like a password — do not share it or commit it to version control.

Storing Your Token Securely

The recommended approach is to store your token in ~/.Renviron, a local file that is never committed to git. This keeps the token out of your scripts entirely.

usethis::edit_r_environ()
# Add the following line, then save and restart R:
# DX_API_TOKEN=your_token_here

After restarting R, the token is available to auth_login() automatically.

Logging In

library(ukbflow)

auth_login()  # reads DX_API_TOKEN from environment

auth_login("your_token_here")

library(ukbflow)

auth_status()  # verify the current session

Checking Authentication Status

auth_status()
#> • User:    "user-XXXXXXXXXXXX"
#> • Project: "project-XXXXXXXXXXXX"

auth_status() returns the current user and active project. Use this to confirm your session before running any analysis.

Listing Available Projects

auth_list_projects()
#> project-XXXXXXXXXXXX : My UKB Project (CONTRIBUTOR)
#> project-YYYYYYYYYYYY : Shared Analysis Project (VIEW)

This returns all RAP projects accessible to your account, along with their project IDs. Project IDs take the form project-XXXXXXXXXXXX and are required for auth_select_project().

Selecting a Project

auth_select_project("project-XXXXXXXXXXXX")
#> ✔ Project selected: "project-XXXXXXXXXXXX"

ukbflow uses project IDs rather than names to avoid ambiguity. Use auth_list_projects() to find the correct ID first.

Once selected, the project context is saved by the dx toolkit and persists across sessions.

Logging Out

auth_logout()
#> ✔ Logged out from DNAnexus.

Logging out invalidates the current DNAnexus session on the remote platform. The local token file is not removed but becomes invalid. A new token must be generated from the DNAnexus platform before logging in again.

Token Expiry

DNAnexus API tokens have a limited validity period set at creation time. When a token expires:

• auth_login() or other dx-dependent functions will fail
• Generate a new token from the DNAnexus platform and log in again:

auth_login("your_new_token_here")

Or update ~/.Renviron with the new token and call auth_login() without arguments.

Full Local → RAP Workflow

library(ukbflow)

auth_login()                                 # authenticate
auth_status()                                # verify session
auth_list_projects()                         # find your project ID
auth_select_project("project-XXXXXXXXXXXX")  # set active project

# ... run your analysis ...

auth_logout()                                # optional: clear session

Getting Help

• ?auth_login, ?auth_status, ?auth_list_projects, ?auth_select_project, ?auth_logout
• DNAnexus documentation
• GitHub Issues