# Authenticating osfr

## 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, 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.

       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 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 and click on the :x: to the right of the PAT you want to deactivate. You can then create a new PAT and reauthenticate.