---
title: "Authenticating osfr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Authenticating osfr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## osfr

This vignette covers how to obtain and use an OSF *personal access token* (PAT) for use with `osfr`.

PATs are required to upload files, create projects/components, access information about your private projects, or download files in your private projects. PATs are not required for accessing information about public projects or downloading public files, but authentication with a PAT will increase the rate limit on the API.

Unauthenticated requests are limited to 100 per hour; Authenticated requests are limited to 10,000 per day. So, if you are planning to make a large number of calls to the API, we suggest authenticating with a PAT even if one is not required for the functions you are running.

## Creating an OSF PAT

To create an OSF PAT, log into OSF through your browser, navigate to the [OSF settings page](https://osf.io/settings/tokens/), and click the **create token** button. You will need to create a PAT with at least `osf.read_full` scope; if you want to be able to edit information through the package, you will also need the PAT to have `osf.write_full` permissions. Once the PAT is created, save it in a safe space.

## Using your PAT

You can authenticate in two different ways:

1. Call the `osf_auth()` function in the console at the start of each new session and paste in your PAT. 

   ```r
   osf_auth("ThIsIsNoTaReAlPaTbUtYoUgEtIt")
   ```

   Your PAT functions like a password, so it should **not** be hard coded into any scripts, ever.

2. To authenticate automatically, store the PAT as an environment variable named `OSF_PAT`, which osfr will detect upon being loaded. One way to do this is to create a `.Renviron` file in your home or project working directory that defines `OSF_PAT`. 

    If you'd like to learn more about `.Renviron` files, the [R Startup chapter](https://rstats.wtf/r-startup.html) of *What They Forgot to Teach You About R* is highly recommended.

## Removing a PAT

If your PAT has accidentally been publicly released in the world, you should deactivate that PAT. To do this, navigate to the [OSF settings page](https://osf.io/settings/tokens/) and click on the :x: to the right of the PAT you want to deactivate. You can then create a new PAT and reauthenticate.