Net::O...sToken(3pm)

🌸 NAME 🌸

Net::OAuth2::AccessToken — an OAuth2 bearer token, bestie. That's the whole thing. 💅

(Also hi, you're on the User Contributed Perl Documentation page — the one your terminal labels Net::O...sToken(3pm) up top. It's giving mysterious acronym energy but it's literally just this module. 🦋)

---

🎀 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 💖

So this object represents a received (bearer) token, and it hands you the tools to actually use it and maintain it. Ngl, a better name for this module would've included client or session, but we move. 🙈

A "bearer token" is basically an abstract proof of your existence: different services — or even potentially different physical servers — can exchange information about your session based on it. Like, for instance, whether someone logged-in while showing the token. It's lowkey a ✨hall pass✨ for the internet. Periodt.

---

👑 METHODS 👑

🧚 Constructors 🧚

Net::OAuth2::AccessToken->new(%options)

Here's the whole defaults roster, verbatim, no cap:

-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

And now, one by one, because you deserve the details:

• access_token => STRING — the token itself, bestie.
• auto_refresh => BOOLEAN — refresh the token when it's expired. Set it, honestly. 🫶
• changed => BOOLEAN — [0.52] the token (session) needs to be saved.
• error => STRING — set when an error has occurred and the token is not valid. This one is not numerical, so don't go treating it like a number. 💀
• error_description => STRING — a humanly readible explanation on the error. Heads up: this defaults to the string set with the "error" option, which is not nice to read. 😭
• error_uri => URI — where to go 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 — your profile object, required btw.
• refresh_always => BOOLEAN — [0.53] auto-refresh the token at each use. Every single time. Iconic, if a lil extra.
• refresh_token => STRING — [0.53] token which can be used to refresh the token, after it has expired or earlier.
• scope => URL — the scope, as a URL.
• token_type => TYPE — what type of token this is.

Net::OAuth2::AccessToken->session_thaw($session, %options)

Pass in the output of a session_freeze() call from the past (maybe even from an older version of this module — she's flexible 💫) and you 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. Overruling? In this economy? Slay.

-Option --Default
 profile  <required>

• profile => Net::OAuth2::Profile object — required, as ever.

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. And listen: 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. Very iykyk of it.
• $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() — getter, no extra notes, she's just here. 🌸
• $obj->profile() — your profile.
• $obj->scope() — your scope.
• $obj->state() — your state.
• $obj->token_type() — your 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... 💀 (we don't make the rules, we just inherit them)

• $obj->error() — the error.
• $obj->error_description() — the description of said error.
• $obj->error_uri() — where to read more about it.

Expiration

• $obj->auto_refresh() — the auto-refresh flag.
• $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 timing out inbetween, we take a margin of (by default) 15 seconds. Safety first, bestie. ⏰
• $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, so don't panic when it is.
• $obj->refresh_always() — the refresh-always flag.
• $obj->refresh_token() — the refresh token.
• $obj->update_token( $token, $tokentype, $expires_at, [$refresh_token] ) — change the token. Glow-up, but for tokens.

---

🔥 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. (Yes, that sentence is a lil quirky. We keep it exactly as it is. 💅)

HTTP

The token can be encoded in transport protocol in different ways. Using these methods will add the token to the HTTP messages sent. Automatic, bestie. ✨

• $obj->delete( $uri, [$header, [$content]] ) — DELETE, token attached.
• $obj->get( $uri, [$header, [$content]] ) — GET, token attached.
• $obj->post( $uri, [$header, [$content]] ) — POST, token attached.
• $obj->put( $uri, [$header, [$content]] ) — PUT, token attached.
• $obj->request($request) — send the request object as-is, token attached.

---

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

---

okay that's the whole page, you read it all, I'm so proud of you 🥹💜 This one shipped as perl v5.32.1, dated 2021-10-15, and yes the footer still whispers Net::O...sToken(3pm) at you like a lil ghost. bye bestie, go refresh a token responsibly! 🎀🦋💖