WWW::OAuth(3pm)

✨ WWW::OAuth — the manual page, but make it cute ✨

okay bestie so this is WWW::OAuth(3pm), a Perl module that does Portable OAuth 1.0 authentication, and I am obsessed 💖

---

💅 NAME 💅

WWW::OAuth — Portable OAuth 1.0 authentication 🎀

---

🦋 SYNOPSIS 🦋

use WWW::OAuth;

my $oauth = WWW::OAuth->new(
  client_id => $client_id,
  client_secret => $client_secret,
  token => $token,
  token_secret => $token_secret,
);

# Just retrieve authorization header
my $auth_header = $oauth->authorization_header($http_request, { oauth_callback => $url });
$http_request->header(Authorization => $auth_header);

# HTTP::Tiny
use HTTP::Tiny;
my $res = $oauth->authenticate(Basic => { method => 'GET', url => $url })
  ->request_with(HTTP::Tiny->new);

# HTTP::Request
use HTTP::Request::Common;
use LWP::UserAgent;
my $res = $oauth->authenticate(GET $url)->request_with(LWP::UserAgent->new);

# Mojo::Message::Request
use Mojo::UserAgent;
my $tx = $ua->build_tx(get => $url);
$tx = $oauth->authenticate($tx->req)->request_with(Mojo::UserAgent->new);

like, look at that. five whole vibes in one code block. no cap. 🫶

---

🌸 DESCRIPTION 🌸

so WWW::OAuth implements OAuth 1.0 request authentication according to RFC 5849 <http://tools.ietf.org/html/rfc5849> (which sometimes gets called OAuth 1.0A, iykyk).

and here's the important part, bestie, so listen up: it does not implement the user agent requests needed for the complete OAuth 1.0 authorization flow 😭. it only prepares and signs requests, and the rest is on your application. that's the deal. it can authenticate requests for LWP::UserAgent, Mojo::UserAgent, HTTP::Tiny, and it can be extended to operate on other types of requests 💅

some user agents can be configured to automatically authenticate each request with a WWW::OAuth object, which is honestly so iconic of them:

# LWP::UserAgent
my $ua = LWP::UserAgent->new;
$ua->add_handler(request_prepare => sub { $oauth->authenticate($_[0]) });

# Mojo::UserAgent
my $ua = Mojo::UserAgent->new;
$ua->on(start => sub { $oauth->authenticate($_[1]->req) });

---

🎀 RETRIEVING ACCESS TOKENS 🎀

okay so the process of retrieving access tokens and token secrets for authorization on behalf of a user? it may differ among various APIs, but it follows this general format (and lol, error checking is left as an exercise to the reader 🙈):

use WWW::OAuth;
use WWW::OAuth::Util 'form_urldecode';
use HTTP::Tiny;
my $ua = HTTP::Tiny->new;
my $oauth = WWW::OAuth->new(
  client_id => $client_id,
  client_secret => $client_secret,
);

# Request token request
my $res = $oauth->authenticate({ method => 'POST', url => $request_token_url },
  { oauth_callback => $callback_url })->request_with($ua);
my %res_data = @{form_urldecode $res->{content}};
my ($request_token, $request_secret) = @res_data{'oauth_token','oauth_token_secret'};

now, the returned request token must be used to construct a URL for the user to go to and authorize your application 🌈. the exact method differs by API, fr fr. the user will usually be redirected to the $callback_url passed earlier after authorizing, with a verifier token that can be used to retrieve the access token and secret 💖

# Access token request
$oauth->token($request_token);
$oauth->token_secret($request_secret);
my $res = $oauth->authenticate({ method => 'POST', url => $access_token_url },
  { oauth_verifier => $verifier_token })->request_with($ua);
my %res_data = @{form_urldecode $res->{content}};
my ($access_token, $access_secret) = @res_data{'oauth_token','oauth_token_secret'};

finally — and this is the part where you get to relax — the access token and secret can now be stored and used to authorize your application on behalf of this user 👑

$oauth->token($access_token);
$oauth->token_secret($access_secret);

---

💜 ATTRIBUTES 💜

WWW::OAuth implements the following attributes. get comfy, there's a few 🦋

🍓 client_id

my $client_id = $oauth->client_id;
$oauth        = $oauth->client_id($client_id);

Client ID used to identify application (sometimes called an API key or consumer key). Required for all requests. periodt.

🍓 client_secret

my $client_secret = $oauth->client_secret;
$oauth            = $oauth->client_secret($client_secret);

Client secret used to authenticate application (sometimes called an API secret or consumer secret). Required for all requests. yeah, both of them. always. 💅

🍓 token

my $token = $oauth->token;
$oauth    = $oauth->token($token);

Request or access token used to identify resource owner. Leave it undefined for temporary credentials requests (request token requests) 👀

🍓 token_secret

my $token_secret = $oauth->token_secret;
$oauth           = $oauth->token_secret($token_secret);

Request or access token secret used to authenticate on behalf of resource owner. Leave it undefined for temporary credentials requests (request token requests) 👀

🍓 signature_method

my $method = $oauth->signature_method;
$oauth     = $oauth->signature_method($method);

Signature method, can be "PLAINTEXT", "HMAC-SHA1", "RSA-SHA1", or a custom signature method. For "RSA-SHA1" or custom signature methods, a "signer" must be provided. Defaults to "HMAC-SHA1". ✨

🍓 signer

my $signer = $oauth->signer;
$oauth     = $oauth->signer(sub {
  my ($base_str, $client_secret, $token_secret) = @_;
  ...
  return $signature;
});

Coderef which implements the "signature_method". a default signer is provided for signature methods "PLAINTEXT" and "HMAC-SHA1"; this attribute is required for other signature methods 😤. for signature method "RSA-SHA1", this attribute may also be an object which has a "sign" method like Crypt::OpenSSL::RSA.

the signer is passed the computed signature base string, the client secret, and (if present) the token secret, and must return the signature string. that's the contract bestie, no take-backs 🤝

---

🌟 METHODS 🌟

WWW::OAuth implements the following methods. main character energy only.

🧚 authenticate

$container = $oauth->authenticate($container, \%oauth_params);
my $container = $oauth->authenticate($http_request, \%oauth_params);
my $container = $oauth->authenticate(Basic => { method => 'GET', url => $url }, \%oauth_params);

Wraps the HTTP request in a container with "oauth_request" in WWW::OAuth::Util, then sets the Authorization header using "authorization_header" to sign the request for OAuth 1.0 🔥. an optional hashref of OAuth parameters will be passed through to "authorization_header". Returns the container object.

🧚 authorization_header

my $auth_header = $oauth->authorization_header($container, \%oauth_params);
my $auth_header = $oauth->authorization_header($http_request, \%oauth_params);
my $auth_header = $oauth->authorization_header(Basic => { method => 'GET', url => $url }, \%oauth_params);

Forms an OAuth 1.0 signed Authorization header for the passed request. as in "authenticate", the request may be specified in any form accepted by "oauth_request" in WWW::OAuth::Util. OAuth protocol parameters (starting with "oauth_" or the special parameter "realm") may be optionally specified in a hashref and will override any generated protocol parameters of the same name (they should not be present in the request URL or body parameters — careful, bestie 🫣). Returns the signed header value ✨

---

💖 HTTP REQUEST CONTAINERS 💖

Request containers provide a unified interface for "authenticate" to parse and update HTTP requests. They must perform the Role::Tiny role WWW::OAuth::Request. Custom container classes can be instantiated directly or via "oauth_request" in WWW::OAuth::Util. slay, extensibility 💅

🎀 Basic

WWW::OAuth::Request::Basic contains the request attributes directly, for user agents such as HTTP::Tiny that do not use request objects.

🎀 HTTP_Request

WWW::OAuth::Request::HTTP_Request wraps a HTTP::Request object, which is compatible with several user agents including LWP::UserAgent, HTTP::Thin, and Net::Async::HTTP.

🎀 Mojo

WWW::OAuth::Request::Mojo wraps a Mojo::Message::Request object, which is used by Mojo::UserAgent via Mojo::Transaction.

---

💀 BUGS 💀

Report any issues on the public bugtracker. 🙏

This module was developed primarily to interface with the Twitter API, which is now functionally unusable, so further development of this module is unlikely without another use case. 😭 that's the tea. it's giving "abandoned but beloved."

---

👑 AUTHOR 👑

Dan Book <dbook@cpan.org>

---

🌈 COPYRIGHT AND LICENSE 🌈

This software is Copyright (c) 2015 by Dan Book.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

---

⭐ SEE ALSO ⭐

• Net::OAuth
• Mojolicious::Plugin::OAuth2

---

and that's the whole page bestie 🫶 this was WWW::OAuth(3pm) from perl v5.40.1, dated 2025-08-10, signed off with so much love 💖✨🎀 go sign some requests, you absolute icon 🌸🦋