otpauth:// URI Format for TOTP
Master the otpauth:// URI format used to provision TOTP secrets in authenticator apps. Learn every parameter: secret, issuer, algorithm, digits, and period with examples.
Detailed Explanation
The otpauth:// URI Specification
The otpauth:// URI scheme is the standard way to transfer TOTP configuration from a server to an authenticator app. It encodes all parameters needed to generate codes — the secret, algorithm, digit count, time period, and display labels.
URI Structure
otpauth://totp/ISSUER:ACCOUNT?secret=BASE32&issuer=ISSUER&algorithm=SHA1&digits=6&period=30
Breaking this down:
- Scheme:
otpauth:// - Type:
totp(orhotpfor counter-based) - Label:
ISSUER:ACCOUNT— displayed in the authenticator app - Parameters: query string with configuration values
Required Parameters
| Parameter | Description | Example |
|---|---|---|
secret |
Base32-encoded shared secret (no padding) | JBSWY3DPEHPK3PXP |
Optional Parameters
| Parameter | Default | Description |
|---|---|---|
issuer |
— | Service name (e.g., GitHub, AWS) |
algorithm |
SHA1 |
Hash algorithm: SHA1, SHA256, SHA512 |
digits |
6 |
Code length: 6 or 8 |
period |
30 |
Time step in seconds |
Complete Examples
Basic (defaults):
otpauth://totp/GitHub:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub
Custom configuration:
otpauth://totp/Corp:admin@internal?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=Corp&algorithm=SHA256&digits=8&period=60
Label Formatting Rules
- The label appears before the
?and uses the formatISSUER:ACCOUNT - Both the issuer prefix and the
issuerparameter should be set (for compatibility) - Special characters must be percent-encoded: spaces →
%20,@→%40,:→%3A - The account name typically uses an email address
Common Mistakes
- Padding in Base32: remove trailing
=padding characters from the secret - Missing issuer: some apps display "Unknown" without both the label prefix and parameter
- Incorrect encoding: spaces and special characters in labels must be percent-encoded
- Case sensitivity: the
secretparameter is case-insensitive, butalgorithmvalues must be uppercase
QR Code Generation
The otpauth:// URI is typically encoded as a QR code for easy scanning. The URI string is passed directly to a QR code generator — no additional encoding is needed beyond standard URI percent-encoding.
Use Case
Developers implementing TOTP enrollment flows need to construct valid otpauth:// URIs that authenticator apps can parse correctly. This reference is essential when building QR code provisioning screens, debugging why an authenticator app rejects or misconfigures a secret, or implementing programmatic TOTP setup via deep links. Getting the URI format right on the first try avoids frustrating users during the 2FA enrollment process.