How to use the otpauth uri builder and reader
- Choose whether to build a TOTP (time based) address, an HOTP (counter based) address or read one you already have.
- To build one, enter the issuer, the account name and the base32 secret, then choose the algorithm and digits, and the period (TOTP) or the starting counter (HOTP).
- To read one, paste the otpauth address and look at the table of parts it holds.
- Copy the address, or use the QR code generator to turn it into an image an authenticator app can scan.
Formula
otpauth://totp/ISSUER:ACCOUNT?secret=BASE32&issuer=ISSUER&algorithm=SHA1&digits=6&period=30
otpauth://hotp/ISSUER:ACCOUNT?secret=BASE32&issuer=ISSUER&algorithm=SHA1&digits=6&counter=0
The issuer and account name are percent-encoded, and the colon between them is left as it is. The secret is base32 in capital letters without padding, so its length must make a whole number of bytes (a length that leaves 0, 2, 4, 5 or 7 characters over a multiple of 8).
A test secret
With the issuer Example Co, the account alice@example.com and the well-known test secret JBSWY3DPEHPK3PXP, the page builds otpauth://totp/Example%20Co:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example%20Co&algorithm=SHA1&digits=6&period=30. The secret is 16 characters, which is 10 bytes or 80 bits.
Reading the address from the Google Authenticator documentation, otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example, gives the issuer Example, the account alice@google.com, SHA1, 6 digits and a 30 second period, which are the defaults when those parts are missing.
What is inside the address
An otpauth address holds everything an authenticator app needs to generate codes: the type, a label for the account, the secret key and the settings for the code. The label shows in the app, and the issuer is the service name. Many apps read the issuer from the label, from the issuer parameter or from both, and warn when they differ, which the page also notes.
The secret is the sensitive part. Anyone who has it can generate the same codes, so treat the address like a password. For testing, use a made-up secret, such as the one in the example, and the TOTP Code Generator to see the codes it produces.
Compatibility
Some authenticator apps ignore the algorithm, digits and period and always use SHA1, six digits and 30 seconds, even when the address says otherwise. If your service uses different settings, test the result in the app your users will use. Secrets of fewer than 16 characters are accepted but flagged, because most services issue longer ones.
To convert the secret to and from bytes, use the Base32 Encoder and Decoder. To turn the address into a scannable image, use the QR Code Generator, and to make a strong password for the account, the Password Generator.
Assumptions and limits
- Only SHA1, SHA256 and SHA512 are accepted for the algorithm, and the digits must be 6, 7 or 8.
- A period is a whole number of seconds from 1 to 86,400, and a counter is a whole number of 0 or more.
- The page does not draw a QR code. Use the QR code generator for that.
- Spaces, hyphens and trailing equals signs in a secret are removed before the secret is checked.
- Nothing typed here leaves your browser. The CSV export contains the secret, so handle it carefully.
Frequently asked questions
What is the difference between TOTP and HOTP?
A TOTP code changes with the clock, usually every 30 seconds. An HOTP code changes each time a counter increases, such as when a button is pressed. The address for HOTP needs a starting counter instead of a period.
Why does the page reject my secret?
A base32 secret uses only the letters A to Z and the digits 2 to 7, and its length must be a whole number of bytes. The page names the first bad character, or tells you the length is wrong.
Why is the colon not encoded in the label?
The colon separates the issuer from the account name, and apps split the label there. The issuer and the account name are encoded on their own, so a colon inside either of them is not allowed.
Is the address safe to share?
No. It contains the secret that generates every code. Share it only with the person who will scan it, and never post it publicly.