TOTP -- Time-Based One-Time Passwords

Generates TOTP secrets and codes per RFC 6238. Unlike other engines, TOTP is built into the Arcan core -- no plugin installation needed.

Overview

The TOTP engine generates shared secrets and provisioning URIs for time-based one-time password authentication. It is commonly used to seed MFA for user accounts or service-to-service TOTP verification.

Because TOTP is a built-in engine, it is available immediately after starting the Arcan server with no additional setup.

Use Cases

• MFA seed generation -- generate TOTP secrets for user accounts during onboarding
• Service account TOTP -- issue rotating codes for service-to-service authentication
• Provisioning QR codes -- return otpauth:// URIs that can be rendered as QR codes for authenticator apps (Google Authenticator, Authy, 1Password, etc.)

Operations

generate

Creates a new TOTP secret, returns the secret key, a provisioning URI, and the current OTP code.

Request:

curl -s -X POST https://localhost:8443/api/v1/realms/default/engines/totp/generate \
  -H "Authorization: Bearer arc_xxx" \
  -H "Content-Type: application/json" \
  -d '{"issuer": "MyApp", "account": "[email protected]"}'

Request body:

Field	Type	Required	Description
issuer	string	Yes	The issuer name displayed in authenticator apps
account	string	Yes	The account identifier (typically an email address)

Response:

{
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "provisioning_uri": "otpauth://totp/MyApp:user%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyApp&algorithm=SHA1&digits=6&period=30",
    "current_otp": "482936"
  }
}

Response fields:

Field	Description
secret	Base32-encoded shared secret. Store this securely -- it is the root of the TOTP chain.
provisioning_uri	otpauth:// URI for QR code generation. Scan with any TOTP authenticator app.
current_otp	The current 6-digit TOTP code, valid for the current 30-second window.

Configuration

TOTP uses standard RFC 6238 defaults:

Parameter	Value
Algorithm	SHA-1
Digits	6
Period	30 seconds

These defaults are compatible with all major authenticator apps.

Usage

# Generate a TOTP secret for a user
curl -s -X POST https://localhost:8443/api/v1/realms/default/engines/totp/generate \
  -H "Authorization: Bearer arc_xxx" \
  -H "Content-Type: application/json" \
  -d '{"issuer": "MyApp", "account": "[email protected]"}' | jq .

# Use the provisioning_uri to generate a QR code
# (e.g., with qrencode CLI or any QR library)
# qrencode -o qr.png "otpauth://totp/MyApp:user%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyApp"

Security Notes

• The secret field is the shared secret. Treat it with the same care as a password -- store it encrypted in Arcan's KV engine or a secure database column.
• TOTP codes are valid for a single 30-second window. Most implementations accept codes from the previous and next window as well (clock skew tolerance).
• The current_otp in the response is provided for convenience (e.g., automated verification flows). Do not log it.
• SHA-1 is used for maximum compatibility with authenticator apps. While SHA-1 has known collision weaknesses, TOTP's use of HMAC-SHA-1 remains secure for this purpose per RFC 6238.