@otplib/uri

@otplib/uri

Parse and generate otpauth:// URIs for OTP account provisioning.

Installation

npm install @otplib/uri
pnpm add @otplib/uri
yarn add @otplib/uri

Overview

The @otplib/uri package provides utilities for working with otpauth:// URIs - the standard format for sharing OTP account information. These URIs are commonly used in QR codes for authenticator app setup.

URI Format

otpauth://TYPE/LABEL?PARAMETERS

• TYPE: totp or hotp
• LABEL: issuer:account or just account
• PARAMETERS: secret, issuer, algorithm, digits, period/counter

Example:

otpauth://totp/GitHub:[e-mail]?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY&issuer=GitHub

Parsing URIs

Basic Parsing

import { parse } from "@otplib/uri";

const uri =
  "otpauth://totp/GitHub:[e-mail]?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY&issuer=GitHub";
const result = parse(uri);

console.log(result);
// {
//   type: 'totp',
//   label: 'GitHub:[e-mail]',
//   params: {
//     secret: 'GEZDGNBVGY3TQOJQGEZDGNBVGY',
//     issuer: 'GitHub'
//   }
// }

When a query parameter is repeated, otplib parses and validates only its first occurrence, matching URLSearchParams.get(). Later occurrences are ignored without decoding their values. A bare parameter such as algorithm counts as the first occurrence with an empty value. The OTPAuth URI format does not define duplicate-parameter behavior, so avoid duplicates when interoperability matters.

Parsing preserves optionality rather than materializing defaults: an absent, bare, or empty algorithm parameter leaves params.algorithm undefined. OTP consumers apply the SHA-1 default when they use the parsed result.

Extracting Account Details

import { parse } from "@otplib/uri";

const uri = "otpauth://totp/ACME%20Corp:[e-mail]?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY";
const { label, params } = parse(uri);

// Split label to get issuer and account
const [issuer, account] = label.includes(":") ? label.split(":") : [params.issuer, label];

console.log("Issuer:", issuer); // 'ACME Corp'
console.log("Account:", account); // '[e-mail]'
console.log("Secret:", params.secret);

Error Handling

import {
  parse,
  URIParseError,
  InvalidURIError,
  MissingParameterError,
  InvalidParameterError,
} from "@otplib/uri";

try {
  const result = parse("invalid-uri");
} catch (error) {
  if (error instanceof InvalidURIError) {
    console.error("Not a valid otpauth:// URI");
  } else if (error instanceof MissingParameterError) {
    console.error("Missing required parameter (e.g., secret)");
  } else if (error instanceof InvalidParameterError) {
    console.error("Invalid parameter value");
  }
}

Generating URIs

TOTP URI

import { generateTOTP } from "@otplib/uri";

const uri = generateTOTP({
  issuer: "ACME Corp",
  label: "[e-mail]",
  secret: "GEZDGNBVGY3TQOJQGEZDGNBVGY",
});

console.log(uri);
// 'otpauth://totp/ACME%20Corp:john%40example.com?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY&issuer=ACME%20Corp'

TOTP with Custom Options

import { generateTOTP } from "@otplib/uri";

const uri = generateTOTP({
  issuer: "GitHub",
  label: "[e-mail]",
  secret: "GEZDGNBVGY3TQOJQGEZDGNBVGY",
  algorithm: "sha256", // Non-default algorithm
  digits: 8, // 8-digit tokens
  period: 60, // 60-second period
});

HOTP URI

import { generateHOTP } from "@otplib/uri";

const uri = generateHOTP({
  issuer: "MyApp",
  label: "user123",
  secret: "GEZDGNBVGY3TQOJQGEZDGNBVGY",
  counter: 0, // Starting counter
});

console.log(uri);
// 'otpauth://hotp/MyApp:user123?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY&issuer=MyApp&counter=0'

Low-Level Generation

For more control, use the generate function directly:

import { generate } from "@otplib/uri";

const uri = generate({
  type: "totp",
  label: "CustomApp:[e-mail]",
  params: {
    secret: "GEZDGNBVGY3TQOJQGEZDGNBVGY",
    issuer: "CustomApp",
    algorithm: "sha1",
    digits: 6,
    period: 30,
  },
});

Google Authenticator Compatibility

[!WARNING] For the widest Google Authenticator interoperability, use the standard defaults:

• sha1 algorithm
• 6 digits
• 30 second period for TOTP
• Issuer should be included in both label and parameter

Some authenticator versions ignore the algorithm, digits, or period parameter, so non-default values may not be honored.

Compatible URI

import { generateTOTP } from "@otplib/uri";

// This URI uses the widely interoperable defaults
const uri = generateTOTP({
  issuer: "MyService",
  label: "[e-mail]",
  secret: "GEZDGNBVGY3TQOJQGEZDGNBVGY",
  // algorithm: 'sha1',  // Default, compatible
  // digits: 6,          // Default, compatible
  // period: 30,         // Default, compatible
});

QR Code Integration

Generate a QR code for the URI using any QR library:

import { generateTOTP } from "@otplib/uri";
import QRCode from "qrcode"; // Example library

const uri = generateTOTP({
  issuer: "MyApp",
  label: "[e-mail]",
  secret: "GEZDGNBVGY3TQOJQGEZDGNBVGY",
});

// Generate QR code as data URL
const qrDataUrl = await QRCode.toDataURL(uri);

// Or generate as SVG
const qrSvg = await QRCode.toString(uri, { type: "svg" });

Documentation

Full documentation available at otplib.yeojz.dev:

• Getting Started Guide
• API Reference

License

MIT