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

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

Authentication is required in order to access boards that are not public, and to
make edits. This document explains how to authenticate your access to Trello.

Getting your access token
-------------------------

A secure token is required to authenticate your access to Trello. To obtain it,
login to Trello and visit `https://trello.com/app-key`. You will need to do two
things there:

* Check the value of Allowed origins. Every API request comes from an "origin",
  i.e. a URL. Trello API will only accept authorized requests if they come from
  the allowed origins list, which makes communication with web apps more secure.
  If you are using trelloR locally (eg. from your laptop or PC) then
  `http://localhost:1410` is a good value to use.

* Copy both "key" and "secret".

Back in R, feed the key and secret to the `get_token()` function. This will
trigger first-time authorization in the browser, allowing you to cache your
token locally. You only have to do it once for a given project, unless you opt
out of using cache or the cache file is deleted.

```r
library(trelloR)
my_token = get_token("my-app", key = your_key, secret = your_secret)
```

This will create an object of class `Trello_API_token`. Functions in the TrelloR
package will always try to read cached token when needed, unless you supply
a token object directly. For example, any of these will work with local cache
in place:

```r
my_boards = get_my_boards()
my_boards = get_my_boards("path/to/cache/file")

# Works without a cache file, if `my_token` is a Token object.
my_boards = get_my_boards(my_token)
```

You can create multiple tokens with different names, scope and expiration.
See `?get_token` for additional arguments.

Keep your credentials safe
--------------------------

Keep your key, secret and any token cache in a **safe, non-shared** location.
Using environment variables or packages like [askpass](https://github.com/r-lib/askpass)
are good options.

Token cache is by default stored in a file called `.httr-oauth`. You should avoid
accidentally copying or exporting this file along with other files. To make this
easier, the cache file path is automatically added to `.gitignore`.

If you think the token might have been compromised or you simply do not want to
use it anymore, you should revoke it. Log in to Trello and access your account
settings. To make it easier to recognize tokens you have created, use the
`appname` argument when creating a token.

__Built with__

```{r}
sessionInfo()
```