> For the complete documentation index, see [llms.txt](https://docs.1kosmos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.1kosmos.com/authentication/passwordless-for-web-apps/login-methods/hardware-tokens.md). # Hardware Tokens *** ### Overview Unlike TOTP, HOTP codes are not time-bound - they remain valid until the next code is generated, making them well-suited for offline environments or systems where clock synchronization is unreliable. *** ### Enabling Hardware Tokens Before using hardware tokens, enable them under **Authentication > Multi-Factor Authentication > Login with One-Time Codes**: * Check **Use passcodes from hardware tokens** * Enter a domain and URL in the Token Configuration section The Hardware Tokens dashboard is accessible from **Authentication > Hardware Tokens**. *** ### Managing Tokens Community Administrators with the appropriate permissions can provision, assign, modify, and export tokens from the Hardware Tokens dashboard. {% hint style="info" %} All update actions require the **authentication.hardware-tokens.view** permission plus at least one of: `create`, `update`, or `delete`. {% endhint %} #### Provisioning Tokens Tokens are imported via CSV. Click **Import Tokens** on the dashboard, then upload a file or paste token data directly in this format: ``` ,, ``` The counter field is optional - if omitted, it defaults to 0. Imported tokens start with an **inactive** status and become active on first use. **CSV rules:** * Maximum 25,000 records per upload; file size must not exceed 25MB * Counter must be a non-negative integer (no decimals, negatives, or special characters) * No blank rows between records #### Assigning Tokens to Users Click a token's serial number to open its details, then click **Add User** and enter a username. A single token can be assigned to multiple users, and a single user can hold multiple tokens. #### Removing a User from a Token Open the token details, locate the user under the **Users** section, click the **Delete** icon, and confirm with **Delete User**. #### Viewing Tokens and Users The dashboard has two tabs: * **Tokens** — lists all provisioned tokens with status, assigned user count, and edit/delete options * **Users** — lists users who have tokens assigned, with last active date and the option to remove a user from all tokens #### Modifying a Token Click **Edit** next to a token to update its counter or seed value. Click **Update Token** to save. {% hint style="info" %} The current seed value cannot be read — only replaced. {% endhint %} #### Resynchronizing Tokens Tokens can fall out of sync when the hardware counter is ahead of the server's counter. The server can correct drift of up to **50 counter steps**. If drift exceeds this, manually reset the counter in AdminX before retrying. To resync, click **Edit** on the token, click **Re-sync Token**, generate three sequential passcodes from the device, enter them in the Re-sync Token window, and click **Update**. #### First-Time Token Sync For tokens that have never been used, 1Kosmos prompts users to complete a one-time sync during their first login. On the **Enter your verification code** screen, the user clicks **First login with token? Continue to sync token**, enters three consecutive passcodes, and clicks **Sync Token & Login**. Configure the sync window range (1–500,000) under **Authentication > Multi-Factor Authentication > Hardware Token Sync Window**. {% hint style="info" %} If multiple tokens are assigned to the user, a dropdown lets them select which token to sync. If the token has already been synced, users can click **Already Synced? Continue to Login** instead. {% endhint %} **Event Logs** — `E_TOKEN_MODIFIED` (activity: authentication) and `E_OTP_VERIFIED` (contains hash of the third OTP) share the same `requestId` during a sync. #### Authenticating with a Hardware Token On the login screen, select **Password & OTP**, enter the password, then select **Hardware Token**, generate a passcode from the device, and enter it. #### Exporting Token Data Click **Export Data** on either the **Tokens** or **Users** tab, enter an email address, and click **Generate**. The report is delivered by email when ready. *** ### Event Logs The following events are triggered by hardware token activity: * `E_OTP_VERIFIED` * `E_LOGIN_SUCCEEDED` * `E_LOGIN_FAILED` * `E_TOKEN_LIST_EXPORTED` * `E_TOKEN_ASSIGNMENT_EXPORTED` * `E_TOKEN_ADDED` * `E_TOKEN_MODIFIED` * `E_TOKEN_ASSIGNED` * `E_TOKEN_UNASSIGNED` * `E_TOKEN_DELETED` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.1kosmos.com/authentication/passwordless-for-web-apps/login-methods/hardware-tokens.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.