.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Net::OAuth::Client 3"
.TH Net::OAuth::Client 3 2026-08-21 "perl v5.42.2" "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::OAuth::Client \- OAuth 1.0A Client
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::OAuth::Client;
\&
\&  # client_id is the Consumer Key, client_secret the Consumer Secret.
\&  # Framework\-agnostic: supply your own redirect and session handling.
\&
\&  my $client = Net::OAuth::Client\->new(
\&      $client_id,
\&      $client_secret,
\&      site               => \*(Aqhttps://provider.example/\*(Aq,
\&      request_token_path => \*(Aq/oauth/request_token\*(Aq,
\&      authorize_path     => \*(Aq/oauth/authorize\*(Aq,
\&      access_token_path  => \*(Aq/oauth/access_token\*(Aq,
\&      callback           => \*(Aqhttps://you.example/auth/callback\*(Aq,
\&      session            => \e&session,
\&  );
\&
\&  # 1. Send the user to the provider to authorize.
\&  $client\->authorize_url;
\&
\&  # 2. They return to your callback with oauth_token and oauth_verifier.
\&  my $access_token = $client\->get_access_token($token, $verifier);
\&
\&  # 3. Use the access token to fetch a protected resource.
\&  my $response = $access_token\->get(\*(Aq/profile\*(Aq);
\&  die $response\->status_line unless $response\->is_success;
\&  print $response\->decoded_content;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Net::OAuth::Client represents an OAuth client or consumer.
.PP
WARNING: Net::OAuth::Client is alpha code.  The rest of Net::OAuth is quite
stable but this particular module is new, and is under\-documented and under\-tested.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "new($client_id, $client_secret, %params)" 4
.el .IP "new($client_id, \f(CW$client_secret\fR, \f(CW%params\fR)" 4
.IX Item "new($client_id, $client_secret, %params)"
Create a new Client
.RS 4
.IP \(bu 4
\&\f(CW$client_id\fR
.Sp
AKA Consumer Key \- you get this from the service provider when you register your application.
.IP \(bu 4
\&\f(CW$client_secret\fR
.Sp
AKA Consumer Secret \- you get this from the service provider when you register your application.
.IP \(bu 4
\&\f(CW$params\fR{site}
.IP \(bu 4
\&\f(CW$params\fR{request_token_path}
.IP \(bu 4
\&\f(CW$params\fR{authorize_path}
.IP \(bu 4
\&\f(CW$params\fR{access_token_path}
.IP \(bu 4
\&\f(CW$params\fR{callback}
.IP \(bu 4
\&\f(CW$params\fR{session}
.IP \(bu 4
\&\f(CW$params\fR{allow_v1a_downgrade}
.Sp
Permit the fallback to OAuth 1.0 described in "OAUTH 1.0A AND THE
CALLBACK CONFIRMATION". Off by default.
.RE
.RS 4
.RE
.SS "OAUTH 1.0A AND THE CALLBACK CONFIRMATION"
.IX Subsection "OAUTH 1.0A AND THE CALLBACK CONFIRMATION"
Passing a \f(CW\*(C`callback\*(C'\fR to \f(CW\*(C`new\*(C'\fR selects OAuth 1.0a. In 1.0a the service
provider echoes \f(CW\*(C`oauth_callback_confirmed\*(C'\fR in its request token response,
and later hands the user back with an \f(CW\*(C`oauth_verifier\*(C'\fR that the client
must present when it exchanges the request token for an access token.
.PP
If the provider\*(Aqs request token response does not contain
\&\f(CW\*(C`oauth_callback_confirmed\*(C'\fR, this client cannot use 1.0a. It used to drop
back to plain OAuth 1.0 by itself, and that fallback was invisible: the
access token request is then built from the 1.0 message class, which has
no \f(CW\*(C`verifier\*(C'\fR parameter, so \f(CW\*(C`oauth_verifier\*(C'\fR is quietly left off the
wire even when the caller passed one to "get_access_token". The verifier
is exactly what 1.0a added to stop an attacker starting a flow, getting a
victim to authorize the attacker\*(Aqs request token, and then completing the
exchange \- so an application that asked for 1.0a and silently got 1.0 is
open to that, with nothing to tell it so.
.PP
\&\f(CW\*(C`get_request_token\*(C'\fR now croaks in that situation instead. An application
that has to talk to a provider which is not 1.0a can opt in with
.PP
.Vb 1
\&  allow_v1a_downgrade => 1
.Ve
.PP
which restores the fallback and warns rather than dying.
.SH AUTHOR
.IX Header "AUTHOR"
Originally by Keith Grennan <foss@nearlyfree.org>
.PP
Currently maintained by Robert Rothenberg <perl@rhizomnic.com>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2007\-2012, 2024\-2026 Keith Grennan
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See http://dev.perl.org/licenses/ for more information.