---
name: "oath_authenticate_usersfile"
section: "3"
platform: "linux"
package: "oath-toolkit"
version: "2.6.15-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/oath_authenticate_usersfile"
---

# oath\_authenticate\_usersfile(3)

API function

## NAME

oath\_authenticate\_usersfile - API function

## SYNOPSIS

**#include \<oath.h\>**

**int oath\_authenticate\_usersfile(const char \*** *usersfile***, const char \*** *username***, const char \*** *otp***, size\_t** *window***, const char \*** *passwd***, time\_t \*** *last\_otp***);**

## ARGUMENTS

- const char \* usersfile

  string with user credential filename, in UsersFile format

- const char \* username

  string with name of user

- const char \* otp

  string with one-time password to authenticate

- size\_t window

  how many past/future OTPs to search

- const char \* passwd

  string with password, or NULL to disable password checking

- time\_t \* last\_otp

  output variable holding last successful authentication

## DESCRIPTION

Authenticate user named *username* with the one-time password *otp* and (optional) password *passwd*.  Credentials are read (and updated) from a text file named *usersfile*.

Note that for TOTP the usersfile will only record the last OTP and use that to make sure more recent OTPs have not been seen yet when validating a new OTP.  That logics relies on using the same search window for the same user.

## RETURNS

On successful validation, **OATH\_OK** is returned.  If the supplied *otp* is the same as the last successfully authenticated one-time password, **OATH\_REPLAYED\_OTP** is returned and the timestamp of the last authentication is returned in *last\_otp*. If the one-time password is not found in the indicated search window, **OATH\_INVALID\_OTP** is returned.  Otherwise, an error code is returned.

## REPORTING BUGS

Report bugs to \<oath-toolkit-help@nongnu.org\>. liboath home page: https://oath-toolkit.codeberg.page/ General help using GNU software: http://www.gnu.org/gethelp/

## COPYRIGHT

Copyright © 2009-2026 Simon Josefsson.\
 Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.