GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Net::OAuth2::AccessToken(3) User Contributed Perl Documentation Net::OAuth2::AccessToken(3)

  Net::OAuth2::AccessToken - OAuth2 bearer token

  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;

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.

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 occured, 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);

$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.

$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 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/

2021-09-27 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.