totp_generate_sha256

Generate a time-based one-time password (TOTP) from a Base32-encoded secret using HMAC-SHA256.

warning

SHA-256 TOTP is not widely supported by consumer authenticator apps. Google Authenticator and Authy silently fall back to SHA-1 even when a QR code specifies SHA-256. Only use this tool when the service explicitly requires HMAC-SHA256. For standard authenticator app compatibility, use totp_generate_sha1.

Parameters

Parameter	Type	Required	Description
secret	string	Yes	Base32-encoded TOTP secret, as exported by authenticator apps (e.g. JBSWY3DPEHPK3PXP). Case-insensitive.
digits	integer	No	Number of digits in the generated token. Must be 6 or 8. Defaults to 6.
step	integer	No	Time step in seconds. Defaults to 30.
time	integer	No	Unix timestamp (seconds) to generate the token for. Omit to use the current system time. When provided, valid_for_seconds is omitted from the response.

Response

Field	Type	Description
token	string	The zero-padded OTP token string (e.g. "048271").
valid_for_seconds	integer	Seconds remaining in the current time window. Only present when time was not provided.

Examples

Generate a token using the current system time

{
	"secret": "JBSWY3DPEHPK3PXP"
}

Result:

{
	"token": "739104",
	"valid_for_seconds": 22
}

---

Generate a token for a specific Unix timestamp

{
	"secret": "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ",
	"time": 1700000000
}

Result:

{
	"token": "524938"
}

Errors

Each failure carries a precise code in the response. Argument-schema and server errors are JSON-RPC protocol errors; a rejected value is returned as a tool result with isError: true (so the agent can read the code and self-correct).

Code	When	Delivered as
invalid_arguments	A required argument is missing or the wrong type (e.g. secret is absent, or digits/step/time is not an integer).	protocol error (invalid_params)
invalid_secret	secret is present but is not valid Base32.	tool error (isError)
internal_error	The system clock could not be read (only when time is omitted), or an unexpected server error occurred.	protocol error (internal_error)

Notes

• SHA-256 and SHA-1 produce different tokens for the same secret and time. A token generated with totp_generate_sha256 must be verified with totp_verify_sha256, not with totp_verify_sha1.
• The secret is case-insensitive. It is uppercased internally before decoding.
• valid_for_seconds is omitted when time is provided.