---
title: "Authentication and Project Setup"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Authentication and Project Setup}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  eval     = FALSE
)
```

## 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](https://platform.dnanexus.com)
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.

```{r renviron}
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

```{r auth-login}
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:

```{r auth-login-direct}
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:

```{r auth-rap}
library(ukbflow)

auth_status()  # verify the current session
```

---

## Checking Authentication Status

```{r auth-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

```{r list-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

```{r select-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

```{r auth-logout}
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:

```{r reauth}
auth_login("your_new_token_here")
```

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

---

## Full Local → RAP Workflow

```{r full-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](https://documentation.dnanexus.com)
- [GitHub Issues](https://github.com/evanbio/ukbflow/issues)