# 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

### Local → RAP

    library(ukbflow)

    auth_login()  # reads DX_API_TOKEN from environment

The token is cached locally by the dx toolkit and persists across R sessions. In most local workflows, you only need to log in once — subsequent R sessions usually do not require re-authentication unless the token expires, the local dx session is cleared, or you explicitly log out.

If you prefer to pass the token directly (e.g., in an interactive session), you can do so:

    auth_login("your_token_here")

> Security note: Avoid saving `auth_login("token")` calls in script files. Prefer the `.Renviron` approach for any workflow you intend to save or share.

### RAP → RAP

When running inside the RAP RStudio environment, authentication is handled automatically by the platform. No login step is required:

    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