Provided by: libnet-oauth2-perl_0.67-1_all 
NAME
Net::OAuth2::AccessToken - OAuth2 bearer token
SYNOPSIS
my $auth = Net::OAuth2::Profile::WebServer->new(...);
my $session = $auth->get_access_token($code, ...);
# $session is a Net::OAuth2::AccessToken object
if($session->error)
{ print $session->error_description;
}
my $response = $session->get($request);
my $response = $session->get($header, $content);
print $session->to_string; # JSON
# probably better to set new(auto_refresh), but you may do:
$session->refresh if $session->expired;
DESCRIPTION
This object represents a received (bearer) token, and offers ways to use it and maintain
it. A better name for this module would include client or session.
A "bearer token" is an abstract proof of your existence: different services or potentially
different physical servers are able to exchange information about your session based on
this, for instance whether someone logged-in while showing the token.
METHODS
Constructors
Net::OAuth2::AccessToken->new(%options)
-Option --Default
access_token undef
auto_refresh <false>
changed <false>
error undef
error_description <value of error>
error_uri undef
expires_at undef
expires_in undef
profile <required>
refresh_always BOOLEAN
refresh_token false
scope undef
token_type undef
access_token => STRING
auto_refresh => BOOLEAN
Refresh the token when expired.
changed => BOOLEAN
[0.52] The token (session) needs to be saved.
error => STRING
Set when an error has occurred, the token is not valid. This is not numerical.
error_description => STRING
A humanly readible explanation on the error. This defaults to the string set with
the "error" option, which is not nice to read.
error_uri => URI
Where to find more details about the error.
expires_at => TIMESTAMP
Expire this token after TIMESTAMP (as produced by the time() function)
expires_in => SECONDS
Expire the token SECONDS after the initiation of this object.
profile => Net::OAuth2::Profile object
refresh_always => BOOLEAN
[0.53] Auto-refresh the token at each use.
refresh_token => STRING
[0.53] Token which can be used to refresh the token, after it has expired or
earlier.
scope => URL
token_type => TYPE
Net::OAuth2::AccessToken->session_thaw($session, %options)
Pass in the output of a session_freeze() call in the past (maybe even for an older
version of this module) and get the token object revived. This $session is a HASH.
You may pass any of the parameters for new() as %options, to overrule the values
inside the $session.
-Option --Default
profile <required>
profile => Net::OAuth2::Profile object
example:
my $auth = Net::OAuth2::Profile::WebServer->new(...);
my $token = $auth->get_access_token(...);
my $session = $token->session_freeze;
# now save $session in database or file
...
# restore session
my $auth = Net::OAuth2::Profile::WebServer->new(...);
my $token = Net::OAuth2::AccessToken->session_thaw($session
, profile => $auth);
Accessors
$obj->access_token()
Returns the (base64 encoded version of the) access token. The token will get updated
first, if it has expired and refresh_token is enabled, or when new(auto_refresh) is
set.
It does not matter that the token is base64 encoded or not: it will always need to be
base64 encoded during transport.
$obj->attribute(NAME)
[0.58] Sometimes, the token gets attributes which are not standard; they have no
official accessor (yet?). You can get them with this generic accessor.
$obj->changed( [BOOLEAN] )
[0.52] The session (token) needs to be saved, because any of the crucial parameters
have been modified and "auto_save" is not defined by the profile.
$obj->hd()
$obj->profile()
$obj->scope()
$obj->state()
$obj->token_type()
errors
When the token is received (hence this object created) it be the result of an error. It
is the way the original code was designed...
$obj->error()
$obj->error_description()
$obj->error_uri()
Expiration
$obj->auto_refresh()
$obj->expired( [$after] )
Returns true when the token has an expiration set and that time has passed. We use
this token $after this check: to avoid the token to timeout inbetween, we take (by
default 15 seconds) margin.
$obj->expires_at( [$timestamp] )
Returns the expiration timestamp of this token (true) or "undef" (false) when it is
not set.
$obj->expires_in()
Returns the number of seconds left, before the token is expired. That may be
negative.
$obj->refresh_always()
$obj->refresh_token()
$obj->update_token( $token, $tokentype, $expires_at, [$refresh_token] )
Change the token.
Actions
$obj->refresh()
Refresh the token, even if it has not expired yet. Returned is the new access_token
value, which may be undef on failure.
$obj->session_freeze(%options)
This returns a SESSION (a flat HASH) containing all token parameters which needs to be
saved to be able to restore this token later. This SESSION can be passed to
session_thaw() to get revived.
The "changed" flag will be cleared by this method.
Be sure that your storage is character-set aware. For instance, you probably want to
set 'mysql_enable_utf8' when you store this in a MySQL database. Perl's JSON module
will output utf8 by default.
$obj->to_json()
Freeze this object into JSON. The JSON syntax is also used by the OAuth2 protocol, so
a logical choice to provide. However, generically, the session_freeze() method
provided.
HTTP
The token can be encoded in transport protocol in different ways. Using these method will
add the token to the HTTP messages sent.
$obj->delete( $uri, [$header, [$content]] )
$obj->get( $uri, [$header, [$content]] )
$obj->post( $uri, [$header, [$content]] )
$obj->put( $uri, [$header, [$content]] )
$obj->request($request)
COPYRIGHTS
Copyrights 2013-2019 on the perl code and the related documentation
by [Mark Overmeer <markov@cpan.org>] for SURFnet bv, The Netherlands. For other
contributors see "Changes".
Copyrights 2011-2012 by Keith Grennan.
This program is free software; you can redistribute it and/or modify it under the same
terms as Perl itself. See http://dev.perl.org/licenses/