.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Net::Twitter::Role::OAuth 3pm"
.TH Net::Twitter::Role::OAuth 3pm "2018-01-18" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Twitter::Role::OAuth \- Net::Twitter role that provides OAuth instead of Basic Authentication
.SH "VERSION"
.IX Header "VERSION"
version 4.01043
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::Twitter;
\&
\&  my $nt = Net::Twitter\->new(
\&      traits          => [\*(AqAPI::RESTv1_1\*(Aq, \*(AqOAuth\*(Aq],
\&      consumer_key    => "YOUR\-CONSUMER\-KEY",
\&      consumer_secret => "YOUR\-CONSUMER\-SECRET",
\&  );
\&
\&  # Do some Authentication work. See EXAMPLES
\&
\&  my $tweets = $nt\->friends_timeline;
\&  my $res    = $nt\->update({ status => "I CAN HAZ OAUTH!" });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::Twitter::Role::OAuth is a Net::Twitter role that provides OAuth
authentication instead of the default Basic Authentication.
.PP
Note that this client only works with APIs that are compatible to OAuth authentication.
.SH "IMPORTANT"
.IX Header "IMPORTANT"
Beginning with version 3.02, it is necessary for web applications to pass the
\&\f(CW\*(C`callback\*(C'\fR parameter to \f(CW\*(C`get_authorization_url\*(C'\fR.  In the absence of a
callback parameter, when the user authorizes the application a \s-1PIN\s0 number is
displayed rather than redirecting the user back to your site.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
See the \f(CW\*(C`examples\*(C'\fR directory in this distribution for working examples of both
desktop and web applications.
.PP
Here's how to authorize users as a desktop app mode:
.PP
.Vb 1
\&  use Net::Twitter;
\&
\&  my $nt = Net::Twitter\->new(
\&      traits          => [\*(AqAPI::RESTv1_1\*(Aq, \*(AqOAuth\*(Aq],
\&      consumer_key    => "YOUR\-CONSUMER\-KEY",
\&      consumer_secret => "YOUR\-CONSUMER\-SECRET",
\&  );
\&
\&  # You\*(Aqll save the token and secret in cookie, config file or session database
\&  my($access_token, $access_token_secret) = restore_tokens();
\&  if ($access_token && $access_token_secret) {
\&      $nt\->access_token($access_token);
\&      $nt\->access_token_secret($access_token_secret);
\&  }
\&
\&  unless ( $nt\->authorized ) {
\&      # The client is not yet authorized: Do it now
\&      print "Authorize this app at ", $nt\->get_authorization_url, " and enter the PIN#\en";
\&
\&      my $pin = <STDIN>; # wait for input
\&      chomp $pin;
\&
\&      my($access_token, $access_token_secret, $user_id, $screen_name) = $nt\->request_access_token(verifier => $pin);
\&      save_tokens($access_token, $access_token_secret); # if necessary
\&  }
\&
\&  # Everything\*(Aqs ready
.Ve
.PP
In a web application mode, you need to save the oauth_token and
oauth_token_secret somewhere when you redirect the user to the OAuth
authorization \s-1URL.\s0
.PP
.Vb 2
\&  sub twitter_authorize : Local {
\&      my($self, $c) = @_;
\&
\&      my $nt = Net::Twitter\->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
\&      my $url = $nt\->get_authorization_url(callback => $callbackurl);
\&
\&      $c\->response\->cookies\->{oauth} = {
\&          value => {
\&              token => $nt\->request_token,
\&              token_secret => $nt\->request_token_secret,
\&          },
\&      };
\&
\&      $c\->response\->redirect($url);
\&  }
.Ve
.PP
And when the user returns back, you'll reset those request token and
secret to upgrade the request token to access token.
.PP
.Vb 2
\&  sub twitter_auth_callback : Local {
\&      my($self, $c) = @_;
\&
\&      my %cookie = $c\->request\->cookies\->{oauth}\->value;
\&      my $verifier = $c\->req\->params\->{oauth_verifier};
\&
\&      my $nt = Net::Twitter\->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
\&      $nt\->request_token($cookie{token});
\&      $nt\->request_token_secret($cookie{token_secret});
\&
\&      my($access_token, $access_token_secret, $user_id, $screen_name)
\&          = $nt\->request_access_token(verifier => $verifier);
\&
\&      # Save $access_token and $access_token_secret in the database associated with $c\->user
\&  }
.Ve
.PP
Later on, you can retrieve and reset those access token and secret
before calling any Twitter \s-1API\s0 methods.
.PP
.Vb 2
\&  sub make_tweet : Local {
\&      my($self, $c) = @_;
\&
\&      my($access_token, $access_token_secret) = ...;
\&
\&      my $nt = Net::Twitter\->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
\&      $nt\->access_token($access_token);
\&      $nt\->access_token_secret($access_token_secret);
\&
\&      # Now you can call any Net::Twitter API methods on $nt
\&      my $status = $c\->req\->param(\*(Aqstatus\*(Aq);
\&      my $res = $nt\->update({ status => $status });
\&  }
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "authorized" 4
.IX Item "authorized"
Whether the client has the necessary credentials to be authorized.
.Sp
Note that the credentials may be wrong and so the request may fail.
.ie n .IP "request_access_token(verifier => $verifier)" 4
.el .IP "request_access_token(verifier => \f(CW$verifier\fR)" 4
.IX Item "request_access_token(verifier => $verifier)"
Request the access token, access token secret, user id and screen name for
this user. You must pass the PIN# (for desktop applications) or the
\&\f(CW\*(C`oauth_verifier\*(C'\fR value, provided as a parameter to the oauth callback
(for web applications) as \f(CW$verifier\fR.
.Sp
The user must have authorized this app at the url given by \f(CW\*(C`get_authorization_url\*(C'\fR first.
.Sp
Returns the access_token, access_token_secret, user_id, and screen_name in a
list.  Also sets them internally so that after calling this method, you can
immediately call \s-1API\s0 methods requiring authentication.
.ie n .IP "xauth($username, $password)" 4
.el .IP "xauth($username, \f(CW$password\fR)" 4
.IX Item "xauth($username, $password)"
Exchanges the \f(CW$username\fR and \f(CW$password\fR for access tokens.  This method has
the same return value as \f(CW\*(C`request_access_token\*(C'\fR: access_token, access_token_secret,
user_id, and screen_name in a list. Also, like \f(CW\*(C`request_access_token\*(C'\fR, it sets
the access_token and access_secret, internally, so you can immediately call \s-1API\s0
methods requiring authentication.
.ie n .IP "get_authorization_url(callback => $callback_url)" 4
.el .IP "get_authorization_url(callback => \f(CW$callback_url\fR)" 4
.IX Item "get_authorization_url(callback => $callback_url)"
Get the \s-1URL\s0 used to authorize the user.  Returns a \f(CW\*(C`URI\*(C'\fR object.  For web
applications, pass your applications callback \s-1URL\s0 as the \f(CW\*(C`callback\*(C'\fR parameter.
No arguments are required for desktop applications (\f(CW\*(C`callback\*(C'\fR defaults to
\&\f(CW\*(C`oob\*(C'\fR, out-of-band).
.ie n .IP "get_authentication_url(callback => $callback_url)" 4
.el .IP "get_authentication_url(callback => \f(CW$callback_url\fR)" 4
.IX Item "get_authentication_url(callback => $callback_url)"
Get the \s-1URL\s0 used to authenticate the user with \*(L"Sign in with Twitter\*(R"
authentication flow.  Returns a \f(CW\*(C`URI\*(C'\fR object.  For web applications, pass your
applications callback \s-1URL\s0 as the \f(CW\*(C`callback\*(C'\fR parameter.  No arguments are
required for desktop applications (\f(CW\*(C`callback\*(C'\fR defaults to \f(CW\*(C`oob\*(C'\fR, out-of-band).
.IP "access_token" 4
.IX Item "access_token"
Get or set the access token.
.IP "access_token_secret" 4
.IX Item "access_token_secret"
Get or set the access token secret.
.IP "request_token" 4
.IX Item "request_token"
Get or set the request token.
.IP "request_token_secret" 4
.IX Item "request_token_secret"
Get or set the request token secret.
.SH "DEPRECATED METHODS"
.IX Header "DEPRECATED METHODS"
.IP "oauth" 4
.IX Item "oauth"
Prior versions used Net::OAuth::Simple.  This method provided access to the
contained Net::OAuth::Simple object. Beginning with Net::Twitter 3.00, the
OAuth methods were delegated to Net::OAuth::Simple.  They have since made first
class methods.  Net::Simple::OAuth is no longer used.  A warning will be
displayed when accessing OAuth methods via the <oauth> method.  The \f(CW\*(C`oauth\*(C'\fR
method will be removed in a future release.
.IP "is_authorized" 4
.IX Item "is_authorized"
Use \f(CW\*(C`authorized\*(C'\fR instead.
.IP "oauth_authorization_url" 4
.IX Item "oauth_authorization_url"
Use \f(CW\*(C`get_authorization_url\*(C'\fR instead.
.IP "oauth_token" 4
.IX Item "oauth_token"
.Vb 1
\&   $nt\->oauth_token($access_token, $access_token_secret);
.Ve
.Sp
Use \f(CW\*(C`access_token\*(C'\fR and \f(CW\*(C`access_token_seccret\*(C'\fR instead:
.Sp
.Vb 2
\&   $nt\->access_token($access_token);
\&   $nt\->access_token_secret($access_token_secret);
.Ve
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
This module was originally authored by Tatsuhiko Miyagawa as
\&\f(CW\*(C`Net::Twitter::OAuth\*(C'\fR, a subclass of the \f(CW\*(C`Net::Twitter\*(C'\fR 2.x. It was
refactored into a Moose Role for use in \f(CW\*(C`Net::Twitter\*(C'\fR 3.0 and above by Marc
Mims.  Many thanks to Tatsuhiko for the original work on both code and
documentation.
.SH "AUTHORS"
.IX Header "AUTHORS"
Marc Mims <marc@questright.com>
.PP
Tatsuhiko Miyagawa <miyagawa@bulknews.net>
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::Twitter, Net::Twitter::OAuth::Simple, Net::OAuth::Simple