--- name: "Net::OAuth2::AccessToken" section: "3pm" platform: "linux" package: "libnet-oauth2-perl" version: "0.67-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::OAuth2::AccessToken" --- # Net::OAuth2::AccessToken(3pm) ## 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 changed error undef error_description error_uri undef expires_at undef expires_in undef profile 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 ``` - 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 \\] 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/*