Net::T...::OAuth(3pm)

💖 Net::T...::OAuth(3pm) 💖

okay bestie, welcome to the User Contributed Perl Documentation page for Net::T...::OAuth — she's a Perl manual page and she's serving. sit down, grab a lil snack, we're gonna read this together 🍓

---

✨ NAME ✨

Net::Twitter::Role::OAuth — it's a Net::Twitter role that gives you OAuth instead of Basic Authentication. no cap, that's the whole vibe.

---

🎀 VERSION 🎀

version 4.01043 🫶 she's got a version number and everything, we love a documented queen.

---

🌈 SYNOPSIS 🌈

here's the little starter pack, copy it, don't fight it:

use Net::Twitter;

my $nt = Net::Twitter->new(
    traits          => ['API::RESTv1_1', 'OAuth'],
    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!" });

like… the last line is literally "I CAN HAZ OAUTH!" and I'm obsessed with whoever wrote that 😭 iconic behaviour.

---

💅 DESCRIPTION 💅

Net::Twitter::Role::OAuth is a Net::Twitter role. what does that mean? it means it provides OAuth authentication instead of the default Basic Authentication. glow-up, basically. ✨

and listen — heads up — this client only works with APIs that are compatible to OAuth authentication. so don't come for her with some non-OAuth API and act surprised. she told you.

---

🚨 IMPORTANT 🚨

okay this is the part where I need you to actually pay attention, bestie, because it's giving breaking change.

beginning with version 3.02, it is necessary for web applications to pass the "callback" parameter to "get_authorization_url".

and if you don't? in the absence of a callback parameter, when the user authorizes the application a PIN number is displayed rather than redirecting the user back to your site. so like, no callback, no redirect, just a PIN sitting there. rude? no. documented? yes. 🫠

---

🌸 EXAMPLES 🌸

there's an "examples" directory in this distribution with working examples of both desktop and web applications. go look, it's all there.

---

🖥️ authorizing users as a desktop app, the mode where you just type a PIN 🧚

here's how it goes:

use Net::Twitter;

my $nt = Net::Twitter->new(
    traits          => ['API::RESTv1_1', 'OAuth'],
    consumer_key    => "YOUR-CONSUMER-KEY",
    consumer_secret => "YOUR-CONSUMER-SECRET",
);

# You'll 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#\n";

    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's ready

see? you stash the token and secret in a cookie, a config file or a session database — your call, live your truth. then you check authorized, and if she's not authorized yet you print the URL, wait on <STDIN> for the PIN, chomp it, and hand it to request_access_token. and then — Everything's ready 💚

---

🌐 web application mode, where cookies are the main characters 🍪

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 URL. somewhere. anywhere. just not nowhere. 🙈

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);
}

---

🔁 and when the user comes back… 🔁

when the user returns back, you'll reset those request token and secret to upgrade the request token to access token. it's giving glow up arc 🌈

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
}

save $access_token and $access_token_secret in the database associated with $c->user, mmkay? that's the assignment. 📝

---

🐦 later on, when you actually wanna tweet 🐦

later on, you can retrieve and reset those access token and secret before calling any Twitter API methods:

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('status');
    my $res = $nt->update({ status => $status });
}

the ... is doing a lot of emotional labour there but go off, you know what goes in it 💀

---

👑 METHODS 👑

okay the main event. every method, no skipping, bestie. 💖

🌟 authorized

tells you whether the client has the necessary credentials to be authorized.

⚠️ careful though — the credentials may be wrong and so the request may fail. authorized-looking ≠ actually authorized, iykyk.

🌟 request_access_token(verifier => $verifier)

requests the access token, access token secret, user id and screen name for this user. you must pass the PIN# (for desktop applications) or the "oauth_verifier" value, provided as a parameter to the oauth callback (for web applications) as $verifier.

the user must have authorized this app at the url given by "get_authorization_url" first. no skipping steps, babe.

returns the access_token, access_token_secret, user_id, and screen_name in a list. and it also sets them internally, so that after calling this method you can immediately call API methods requiring authentication. so convenient. so slay. ✨

🌟 xauth($username, $password)

exchanges the $username and $password for access tokens. same return value as "request_access_token": access_token, access_token_secret, user_id, and screen_name in a list. and, like "request_access_token", it sets the access_token and access_secret internally, so you can immediately call API methods requiring authentication. two-for-one energy 🫶

🌟 get_authorization_url(callback => $callback_url)

gets the URL used to authorize the user. returns a "URI" object. for web applications, pass your applications callback URL as the "callback" parameter. no arguments are required for desktop applications ("callback" defaults to "oob", out-of-band). 🦋

🌟 get_authentication_url(callback => $callback_url)

gets the URL used to authenticate the user with "Sign in with Twitter" authentication flow. returns a "URI" object. for web applications, pass your applications callback URL as the "callback" parameter. no arguments are required for desktop applications ("callback" defaults to "oob", out-of-band). yes, it's a sibling to the one above, no, they are not the same method, read the names. 💅

🌟 access_token

get or set the access token.

🌟 access_token_secret

get or set the access token secret.

🌟 request_token

get or set the request token.

🌟 request_token_secret

get or set the request token secret.

---

💀 DEPRECATED METHODS 💀

these are the old ones. they still exist but they're giving legacy. don't build new stuff on them, bestie.

🪦 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 "oauth" method will be removed in a future release. 😭

so like… it's on the way out. she's packing her bags. goodbye is imminent.

🪦 is_authorized

use "authorized" instead. that's it. that's the whole note. 🔥

🪦 oauth_authorization_url

use "get_authorization_url" instead.

🪦 oauth_token

$nt->oauth_token($access_token, $access_token_secret);

use "access_token" and "access_token_seccret" instead:

$nt->access_token($access_token);
$nt->access_token_secret($access_token_secret);

(the typo in "access_token_seccret" is canon, I do not make the rules 🙈)

---

🌈 ACKNOWLEDGEMENTS 🌈

this module was originally authored by Tatsuhiko Miyagawa as "Net::Twitter::OAuth", a subclass of the "Net::Twitter" 2.x. it was refactored into a Moose Role for use in "Net::Twitter" 3.0 and above by Marc Mims. many thanks to Tatsuhiko for the original work on both code and documentation. 🫶 legendary.

---

💜 AUTHORS 💜

• Marc Mims <marc@questright.com>
• Tatsuhiko Miyagawa <miyagawa@bulknews.net>

---

📜 LICENSE 📜

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. go forth, remix, respect the terms. 🎀

---

🦋 SEE ALSO 🦋

• Net::Twitter
• Net::Twitter::OAuth::Simple
• Net::OAuth::Simple

---

and that's the whole page, bestie!! 🎉 this was perl v5.34.0, dated 2022-06-16, and the page is Net::T...::OAuth(3pm) — she's old, she's wise, she's authenticated. go authorize something. mwah 💅💖