totp_generate_sha1

Generate a time-based one-time password (TOTP) from a Base32-encoded secret using HMAC-SHA1 — the RFC 6238 default algorithm used by Google Authenticator, Authy, and the vast majority of TOTP-enabled services.

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": "482910",
	"valid_for_seconds": 17
}

---

Generate a token for a specific Unix timestamp

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

Result (RFC 6238 test vector):

{
	"token": "287082"
}

---

Generate an 8-digit token

{
	"secret": "JBSWY3DPEHPK3PXP",
	"digits": 8
}

Result:

{
	"token": "48291037",
	"valid_for_seconds": 12
}

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-1 is the correct choice for most services. Google Authenticator, Authy, and the majority of TOTP-enabled websites use HMAC-SHA1. Only use totp_generate_sha256 or totp_generate_sha512 when the service explicitly requires a different algorithm.
• valid_for_seconds is omitted when time is provided. This avoids confusing output when working with historical or test timestamps.
• The secret is case-insensitive. It is uppercased internally before decoding, so both jbswy3dpehpk3pxp and JBSWY3DPEHPK3PXP are accepted.
• Use totp_verify_sha1 to verify a token produced by this tool.