Security · Developer tools

otpauth:// URIs.

Take apart the link inside a 2FA QR code, or build one from a Base32 secret. Follows the Key Uri Format used by authenticator apps. Runs entirely in your browser; nothing is sent anywhere.

How to parse or build an otpauth URI

  1. To read one, paste the otpauth:// link into the box and press Parse URI. The type, secret, issuer, account and settings appear in the form.
  2. To create one, enter the Base32 secret and choose totp or hotp, then set the issuer, account name, algorithm, digits and period or counter.
  3. Press Build URI and copy the result.

The key URI format

The link inside a two-factor setup QR code follows the Key Uri Format used by authenticator apps: otpauth://TYPE/LABEL?PARAMETERS. The type is totp for time-based codes or hotp for counter-based ones. The label is issuer:account. The parameters carry the secret in Base32, the issuer, the algorithm (SHA1, SHA256 or SHA512), the number of digits (6 or 8), the period in seconds for totp and the counter for hotp.

Different apps treat optional values differently. The specification notes that Google Authenticator ignores algorithm, digits and period, so non-default values may behave differently between apps. Use the defaults unless a service requires otherwise.

Secrets stay on your device

The parser runs in your browser, inside an isolated frame on this page that has no network access. Your file is read and written back by your own device, so it is not uploaded to TNAADO or anyone else, and nothing is stored. The advertising on this page sits outside the frame and cannot see what you choose. A two-factor secret is as sensitive as a password, so it is never sent anywhere.

The format

What an otpauth:// link is

When you scan a two-factor QR code, the QR code is only a picture of text, and that text is an otpauth:// URI. It carries everything an authenticator app needs to start producing codes: the type of code, the account label, the shared secret and optional settings. The format was introduced for Google Authenticator and is documented in its Key Uri Format wiki page; many authenticator apps follow it. This tool takes one apart so you can see what a QR code actually says, and builds a new one from a secret so you can test an app or write your own enrolment flow.

Anatomy of the URI

The shape is otpauth://TYPE/LABEL?PARAMETERS.

Worked example

Take otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example, the sample from the Key Uri Format page. Paste it into the parser. It reads as: type totp, issuer Example, account alice@google.com, and a 16-character Base32 secret. Because no algorithm, digits or period are given, the defaults apply: SHA1, 6 digits, 30 seconds. That secret decodes to ten bytes, which is 80 bits. The HOTP specification (RFC 4226) requires a shared secret of at least 128 bits and recommends 160 bits, so a real deployment should use a longer secret: at least 26 Base32 characters, and 32 for the recommended 160 bits. Treat the example as a format illustration, not a model of secret length.

Compatibility is the catch

The wiki states that Google Authenticator ignores the algorithm parameter and the period parameter, and ignored digits on Android and BlackBerry. So a URI asking for SHA256, 8 digits or a 60-second period may be accepted but still produce standard 30-second, 6-digit SHA-1 codes in that app, while other authenticators honour the settings. If you issue your own secrets, the safest choice for broad compatibility is the defaults, and the tool's "include default values" option lets you write them out explicitly if a particular app needs that.

Common mistakes

What this tool does not cover

It parses and builds the text of the URI. It does not draw a QR code, store secrets or check that a service accepts the secret. To see the codes a secret produces, use the TOTP Code Generator; to decode the Base32 itself, see the Base32 tools.

Common mix-ups

  1. RFC 6238: TOTP: Time-Based One-Time Password Algorithm

Checked against these sources on .

Frequently asked questions

What does an otpauth:// URI contain?

It contains the type (totp or hotp), a label that names the issuer and account, and query parameters. The secret parameter is required and holds the Base32 shared key; issuer, algorithm, digits, period and counter are optional or conditional. A 2FA QR code is just this text encoded as an image.

What is the otpauth URI format for TOTP?

The pattern is otpauth://totp/Issuer:account?secret=BASE32SECRET&issuer=Issuer. The defaults are SHA1, 6 digits and a 30-second period, so you only need to add algorithm, digits or period if you want something different.

How do I get the secret out of a 2FA QR code?

Decode the QR code with any scanner that shows the raw text. The value after secret= is the Base32 shared key. Keep it private: anyone who has it can generate your codes, so store it only where you would store the password.

Why does my authenticator ignore the algorithm or period I set?

The Key Uri Format wiki notes that Google Authenticator ignores the algorithm and period parameters, and ignored digits on Android and BlackBerry. Other apps may honour them. For the widest compatibility, stay with SHA1, 6 digits and a 30-second period.

Should the issuer be in the label, the parameter, or both?

Both. The specification recommends using the issuer label prefix and the issuer parameter together, because older Google Authenticator versions rely on the prefix while newer ones use the parameter.

Does the secret need Base32 padding?

No. The padding from RFC 3548 section 2.2 is not required and should be omitted. A secret is made of the letters A to Z and the digits 2 to 7.

How long should a TOTP secret be?

RFC 4226 requires a shared secret of at least 128 bits and recommends 160 bits. In Base32 that is at least 26 characters, and 32 characters for 160 bits. Short example secrets in tutorials are often only 80 bits.

Sources

Advertisement
Advertisement