Net::OAuth2::AccessToken - OAuth2 bearer token

       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/

perl v5.32.1                                       2021-10-15                      Net::OAuth2::AccessToken(3pm)

       This object represents a received (bearer) token, and offers ways to use it and maintain it.  A better
       name for this module would include clientorsession.

       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.

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)

         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;