httr2/man/req_oauth_device.Rd at f5554cffbe7de21d848ba9505427deb47c69c710 · zacdav-db/httr2 · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oauth-flow-device.R
\name{req_oauth_device}
\alias{req_oauth_device}
\alias{oauth_flow_device}
\title{OAuth with device flow}
\usage{
req_oauth_device(
  req,
  client,
  auth_url = NULL,
  pkce = FALSE,
  scope = NULL,
  open_browser = is_interactive(),
  auth_params = list(),
  token_params = list(),
  cache_disk = FALSE,
  cache_key = NULL,
  expiry_margin = 30
)

oauth_flow_device(
  client,
  auth_url = NULL,
  pkce = FALSE,
  scope = NULL,
  open_browser = is_interactive(),
  auth_params = list(),
  token_params = list()
)
}
\arguments{
\item{req}{A httr2 \link{request} object.}

\item{client}{An \code{\link[=oauth_client]{oauth_client()}}.}

\item{auth_url}{Device authorization url; you'll need to discover this by
reading the documentation. Not needed if \code{metadata} was supplied to
\code{\link[=oauth_client]{oauth_client()}}, which sets it from the \code{device_authorization_endpoint}.}

\item{pkce}{Use "Proof Key for Code Exchange"? This adds an extra layer of
security and should always be used if supported by the server.}

\item{scope}{Scopes to be requested from the resource owner.}

\item{open_browser}{If \code{TRUE} (the default in interactive sessions), the
device verification URL will be opened in the user's browser. If \code{FALSE},
the URL is printed to the console and the user must open it themselves.}

\item{auth_params}{A list containing additional parameters passed to
\code{\link[=oauth_flow_auth_code_url]{oauth_flow_auth_code_url()}}.}

\item{token_params}{List containing additional parameters passed to the
\code{token_url}.}

\item{cache_disk}{Should the access token be cached on disk? This reduces
the number of times that you need to re-authenticate at the cost of
storing access credentials on disk.

Learn more in \url{https://httr2.r-lib.org/articles/oauth.html}.}

\item{cache_key}{If you want to cache multiple tokens per app, use this
key to disambiguate them.}

\item{expiry_margin}{Number of seconds before a token's stated expiry that
it should be treated as expired. Increase this for servers that reject
tokens shortly before they expire. Defaults to 30 seconds.}
}
\value{
\code{req_oauth_device()} returns a modified HTTP \link{request} that will
use OAuth; \code{oauth_flow_device()} returns an \link{oauth_token}.
}
\description{
Authenticate using the OAuth \strong{device flow}, as defined by \href{https://datatracker.ietf.org/doc/html/rfc8628}{RFC 8628}.
It's designed for devices that don't have access to a web browser (if you've
ever authenticated an app on your TV, this is probably the flow you've used),
but it also works well from within R.

Learn more about the overall OAuth authentication flow in
\url{https://httr2.r-lib.org/articles/oauth.html}.
}
\examples{
req_auth_github <- function(req) {
  req_oauth_device(
    req,
    client = example_github_client(),
    auth_url = "https://github.com/login/device/code"
  )
}

request("https://api.github.com/user") |>
  req_auth_github()
}