URI::otpauth(3)

💖 URI::otpauth 💖

okay so bestie, real talk: this is the manual for URI::otpauth, a Perl module from the URI family. It's the URI scheme for secret keys for OTP secrets — and yeah, that's exactly the thing you usually find hiding in QR codes. 🎀

---

✨ VERSION ✨

Version 5.29 — that's the one, no cap.

---

🌸 SYNOPSIS 🌸

use URI;

# optauth URI from textual uri
my $uri = URI->new( 'otpauth://totp/Example:alice@google.com?secret=NFZS25DINFZV643VOAZXELLTGNRXEM3UH4&issuer=Example' );

# same URI but created from arguments
my $uri = URI::otpauth->new( type => 'totp', issuer => 'Example', account_name => 'alice@google.com', secret => 'is-this_sup3r-s3cr3t?' );

(and yes, optauth in that first comment is literally how the original spells it — we keep the receipts 💅)

---

🦋 DESCRIPTION 🦋

This URI scheme is defined right here: https://github.com/google/google-authenticator/wiki/Key-Uri-Format/

That's the whole vibe check. Moving on, main character style. ✨

---

👑 SUBROUTINES/METHODS 👑

🫶 "new"

Creates a brand-new URI::otpauth. The arguments you can slide in are listed below:

• account_name — this can be the account name (probably an email address) used when authenticating with this secret. It's an optional field, so no pressure.
• algorithm — the cryptographic hash function (https://en.wikipedia.org/wiki/Cryptographic_hash_function) that should be used. Current values are SHA1 (https://en.wikipedia.org/wiki/SHA-1), SHA256 (https://en.wikipedia.org/wiki/SHA-2), or SHA512 (https://en.wikipedia.org/wiki/SHA-2). Optional field, and it defaults to SHA1.
• counter — this is only required when the type is HOTP. That's the whole rule, iykyk.
• digits — this determines the length (https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#digits) of the code presented to the user. Optional field, defaults to 6 digits.
• issuer — this can be the application / system (https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#issuer) that this secret can be used to authenticate to. Optional field.
• label — this is the issuer and the account name (https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#label) joined with a ":" character. Optional field.
• period — this is the period that the TOTP code is valid for (https://github.com/google/google-authenticator/wiki/Key-Uri-Format/#counter). Optional field, defaults to 30 seconds.
• secret — this is the key (https://en.wikipedia.org/wiki/Key_(cryptography)) that the TOTP (https://en.wikipedia.org/wiki/Time-based_one-time_password) / HOTP (https://en.wikipedia.org/wiki/HMAC-based_one-time_password) algorithm uses to derive the value. It's an arbitrary byte string and it must remain private. 🔒 This field is mandatory — no secret, no deal.
• type — this can be 'hotp' (https://en.wikipedia.org/wiki/HMAC-based_one-time_password) or 'totp' (https://en.wikipedia.org/wiki/Time-based_one-time_password). This field defaults to 'totp'.

ngl bestie, that secret one? Treat it like your deepest darkest secret, because that's literally what it is. Keep it private, fr fr. 🙈

---

💜 "algorithm"

Get or set the algorithm of this otpauth URI.

💜 "account_name"

Get or set the account_name of this otpauth URI.

💜 "counter"

Get or set the counter of this otpauth URI.

💜 "digits"

Get or set the digits of this otpauth URI.

💜 "issuer"

Get or set the issuer of this otpauth URI.

💜 "label"

Get or set the label of this otpauth URI.

💜 "period"

Get or set the period of this otpauth URI.

💜 "secret"

Get or set the secret of this otpauth URI.

💜 "type"

Get or set the type of this otpauth URI.

my $type = $uri->type('hotp');

(look at that — get and set in one iconic little line 🎀)

---

🌈 CONFIGURATION AND ENVIRONMENT 🌈

URI::otpauth requires no configuration files or environment variables. Zero setup, we love a low-maintenance icon. ✨

---

🧚 DEPENDENCIES 🧚

• URI

---

💀 DIAGNOSTICS 💀

• "secret is a mandatory parameter for URI::otpauth" — the secret parameter was not detected for the URI::otpauth->new() method. Yeah. It's mandatory. It said what it said. 😭

---

🍓 INCOMPATIBILITIES 🍓

None reported. (a peaceful, drama-free era 🕊️)

---

⭐ BUGS AND LIMITATIONS ⭐

To report a bug, or to view the current list of bugs, please visit https://github.com/libwww-perl/URI/issues — the devs are literally waiting for you there. 🫶

---

🌸 AUTHOR 🌸

David Dick <ddick@cpan.org>

---

🎀 LICENSE AND COPYRIGHT 🎀

Copyright (c) 2024, David Dick <ddick@cpan.org>.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

---

and that's the whole page bestie — this was perl v5.42.0, dated 2026-09-02, and it's giving iconic documentation energy. slay, go rotate some secrets responsibly 💅✨