🔐 Authentication & Security

Two-Factor Sign-In: How It Works Now

Which ways to sign in you see

• Each VoiceLink server chooses how people sign in (the owner sets it in Admin, Security, Sign-in providers). The web app's welcome screen and sign-in dialog only show the ways this server has turned on, in the owner's order, and use the server's own name.
• A VoiceLink account (email or username, password and two-factor) always works. Client Portal (WHMCS), Mastodon and blind.software only appear when the server offers them. A new server offers VoiceLink accounts only until its owner turns more on.
• The same account works in the iPhone, iPad, Mac, Windows and web apps: add the server in the app and sign in with your email or username, password and two-factor code.

Creating an account

• Web app: on the welcome screen choose "Create an account", or the "Create account" tab in the sign-in dialog. Type a username, your email and a password twice (at least 12 characters and not a common password). If the server sends email, choose Create account, type the 6-digit code from the email in "Code from the email", and choose Create account again. You are signed in straight away.
• If the server isn't taking new accounts, the tab isn't there; ask the owner for an invite.

Forgot your password

• For VoiceLink accounts. In the sign-in dialog, on the VoiceLink tab, choose "Forgot password". Type your email or username and choose "Send reset code". Type the 6-digit code from the email (it works for 15 minutes, once) and a new password, and choose "Set new password".
• If your account has two-factor, you also type a two-factor or recovery code, so an email alone can't take over your account. Your other devices are signed out, and you get an email saying the password changed.
• You always see the same answer whether or not the account exists. After too many wrong codes, wait a while (the same limits as wrong passwords).
• If the server can't send email, the screen says so: ask the server owner to reset your password. Client Portal accounts get an email pointing to the Client Portal, where that password is managed.

Client Portal accounts

• If you sign in with your Client Portal account and it has two-factor turned on, VoiceLink asks for the same 6-digit code the Client Portal uses. The code is checked by the Client Portal itself.
• Turn two-factor on or off, and change your password, in the Client Portal. In the iPhone app, Settings, Security has a link that opens it; in the web app, open Settings, choose the Security tab, and use the "Manage in the Client Portal" link under Two-factor authentication.

VoiceLink accounts

• On iPhone: Settings, Security, Two-Factor tab, then "Set Up Authenticator". Use "Add to Passwords" (or the setup key, read out character by character, or the QR code) and type the 6-digit code to confirm.
• On the web (and Windows, which hosts the same web app): open Settings, choose the Security tab, and under Two-factor authentication choose "Set up two-factor authentication". Add the account with the "Open in my authenticator app" link if you're on the same device, by scanning the QR code with another device, or by typing the setup key, then type the 6-digit code to confirm.
• You then get 10 backup codes. Each works once if you can't get a code. Copy them somewhere safe; "Regenerate backup codes" (web) or "Make New Backup Codes" (iPhone) replaces them.
• To turn two-factor off you need a current code or a backup code.
• Settings, Security also lists devices signed in and how long a device stays trusted after a two-factor code, with a "Sign out other devices" button.

Entering the code

• iPhone and iPad: after your password, VoiceOver moves to the code field. Your iPhone offers the code from Passwords above the keyboard; choose it, or type or paste the 6 digits. Six digits sign you in straight away. "Use a backup code" switches the field to backup codes.
• Mac and web: type the code in the Two-Factor Code field and sign in again. The web app moves focus to that field and reads the message.
• After too many wrong codes, wait 15 minutes.

Admin: configuring two-factor authentication

• In Admin, Modules, "Two-factor authentication" (installed by default on new servers): turn the module on or off, choose which methods people can set up (authenticator app, email code, SMS; passkeys aren't offered yet), and see how many accounts already use it.
• "Who must use it" controls whether two-factor is required for admins and owners, required for everyone, or left as something each person turns on for themselves (the default, so existing users aren't locked out).
• "Reset a user's two-factor" turns it off for one account (by user ID, from Admin, Users) so they can sign back in and set it up again; every reset is written to the server's two-factor audit log with who did it and when.
• The trusted-device window (how many days a device skips a fresh two-factor code) is a deploy setting, security.twoFactorTrustDays, 30 days by default; it's shown to users under Settings, Security.
• Client Portal (WHMCS) two-factor is managed in the Client Portal, not here; this server only checks it during sign-in and shows its status in Settings, Security.

Signing in with Mastodon

• In the web app, open the login dialog, choose the Mastodon tab, type your server (for example mastodon.social, or your full handle like @name@mastodon.social) and choose Connect.
• On iPhone and iPad: Settings, then Sign in (or the Mastodon choice), and in the Mastodon section type your server or handle and choose "Sign In with Mastodon". Your Mastodon server's page opens inside VoiceLink, in a sign-in sheet that shares Safari's sign-in, so if you're already signed in to Mastodon in Safari you only approve VoiceLink. The sheet closes by itself and VoiceOver says you're signed in. Close the sheet to cancel.
• Already signed in to VoiceLink on iPhone? The same section says "Link Mastodon to This Account", which adds Mastodon as another way into your existing account. If that account has two-factor, you're asked for your code as usual.
• Your Mastodon server asks you to approve VoiceLink, then sends you back to VoiceLink signed in. VoiceLink says "Signed in with Mastodon as" and your handle.
• The VoiceLink server does the whole exchange with your Mastodon server and asks for full access (read, write, follow and post), not just your account name, because Mastodon can be your account's main way in. You stay in control of what that means on Mastodon's side (block, mute, post visibility, and so on all still work as you set them there); VoiceLink only uses the access to keep your VoiceLink profile in sync and to follow you if your account moves.
• Unlike most other sign-ins, VoiceLink keeps this access (a Mastodon access token, encrypted at rest, never shown to anyone) instead of letting it go right after you sign in. About once an hour it re-checks it: your display name and photo stay in sync automatically if Mastodon is your primary sign-in (Settings, Security, Sign-in methods), and if your Mastodon account moves to a new one, VoiceLink follows the new account, checks it's real on its own server, and switches your VoiceLink sign-in to it -- no separate action needed, and you're told by email. Remove Mastodon under Sign-in methods any time to revoke this access.
• The first time, VoiceLink makes an account tied to your Mastodon handle, and later Mastodon sign-ins use that same account.
• If that account has two-factor turned on, the web app moves you to the Two-Factor Code field. Type the code and choose Sign In; you don't need your password.
• "Keep me signed in on this device" (on by default) keeps you signed in after you close the browser.
• Each of our VoiceLink servers registers its own entry on your Mastodon server ("VoiceLink (Community)", "VoiceLink (Dev)", and so on, under Mastodon's own Preferences, Authorized apps), so you can tell them apart and revoke just one if you need to.
• Sign-in took too long and came back "expired"? Choose Continue in the dialog that reopens -- it's kept your server, so this is one tap, not retyping it.

Signing in with blind.software

• Web app: on the welcome screen, or at the top of the login dialog, choose "Sign in with blind.software". blind.software opens in the same tab. Sign in there if you aren't already.
• blind.software shows which app and server want you to sign in and what they will see: your blind.software account number and your name. Your email address is only shared if you tick "Also share my email address". Choose Continue, or Cancel to stop.
• You come back to VoiceLink signed in. The first time, VoiceLink makes an account from your blind.software account (no password needed). After that, blind.software remembers your choice and sends you straight back.
• Already have a VoiceLink or Client Portal account? Sign in to it, then go to Settings, Privacy, Linked Sign-ins and choose "Link blind.software". From then on "Sign in with blind.software" opens that same account. If your blind.software email already belongs to a VoiceLink account, VoiceLink won't make a second one; sign in to that account and link it instead.
• If the account has two-factor turned on (VoiceLink or Client Portal), you're asked for your code after blind.software, in the "Finish signing in with blind.software" field. blind.software doesn't have its own two-factor yet.
• "Keep me signed in on this device" (on by default) keeps you signed in after you close the browser, the same as the other sign-ins.
• To unlink: Settings, Privacy, Linked Sign-ins, "Unlink blind.software". This also ends the link on blind.software and signs out devices that signed in with it. If blind.software is the only way into the account, set a VoiceLink password first. You can also unlink VoiceLink on blind.software (My account, Settings, Linked apps); VoiceLink notices within about an hour.
• iPhone, iPad, Mac and Windows apps get the same button in a later update.

Your sign-in methods (Settings, Security, Account)

• Web app: open Settings, choose the Security tab. Under Account, "Sign-in methods" lists every way into your account: Email and password, Mastodon, blind.software and Client Portal. Each item says which one is primary, when it was last used, and has "Make primary" and "Remove" buttons where they apply.
• All of them open the same account. You never get a second account by signing in a different way.
• Add Mastodon: type your Mastodon server or handle and choose "Add Mastodon". Add blind.software: choose "Add blind.software". Client Portal: sign in with Client Account using the same email address. Only the ways this server has turned on are offered.
• Make primary: the primary method is the main way we contact you about sign-in changes. Changing it asks you to confirm it's you, in the "Confirm it's you" form: your two-factor code if two-factor is on, otherwise your VoiceLink password. Your old primary contact gets an email about the change.
• Remove: asks you to confirm in a dialog, and for your two-factor code if two-factor is on. You can't remove the last way into your account, or your email and password (change them instead). Removing blind.software also signs out devices that signed in with it.
• New primary email: under "New primary email address", type the new address and choose "Send code". Type the code from that email and choose "Confirm email". Your email only changes after the code, and your old address is told. An address that already belongs to another VoiceLink account can't be used; accounts are never merged by email.
• Lost your primary? If your email address no longer works, sign in with any other method you added (for example Mastodon or blind.software), then set a new primary email or make that method primary. That's why it's worth adding a second method now.
• Your password and two-factor settings stay as they are when you change sign-in methods. Passkeys show here as a second factor only; they aren't a way to sign in on their own yet.
• Using several of our VoiceLink servers? Sign in on one and the others know you: they use their own account for you when one matches (the same email, or the same linked Mastodon, blind.software or Client Portal account). Each server decides your role itself.

App tokens (Settings, Security, App tokens)

• An app token lets one app or device use your VoiceLink account with only the permissions you choose, without your password. Use one for a script, a status board, a helper app, or an app on your own VoiceLink server.
• Create one: web app, Settings, Security tab, "App tokens". Type a name (the app or device it's for), tick the permissions, optionally set how many days until it expires, and choose "Create token". VoiceLink asks you to confirm it's you (your two-factor code, or your password when two-factor is off).
• The new token is shown once, in the "New token" field with a "Copy token" button. Paste it into the app, then choose "Done, hide the token". VoiceLink only keeps a scrambled copy, so it can't show it again; if you lose it, revoke it and make a new one.
• Permissions: "See your profile" (name, email, role); "Use rooms" (list rooms, join, talk and listen); "See servers you own or manage" (read-only admin screens, only on servers where you're the owner or an admin); "Manage servers you own or manage" (change settings, users and rooms there). A token without a server permission is a normal user everywhere, even if your account is an owner.
• A token can never create or revoke tokens, change your sign-in methods, password or two-factor, or make a normal sign-in. Those always need you signed in normally.
• The table lists each token's name, permissions, the first few characters of the token, when it was made, last used and when it expires, with a "Revoke" button per token (it asks you to confirm). A revoked token stops working at once.
• App tokens belong to your VoiceLink account, so they keep working when the Client Portal is down. On our other servers the token shows who you are; each server decides your role there, within the token's permissions.
• For app developers: send the token as Authorization: Bearer on the API, or as token in the socket register-session event.

Connected apps in the Client Portal

• Clients can also see their app tokens in the Client Portal: sign in, open Account, then "Connected apps". It lists your app tokens (with a "Revoke" button for each) and the VoiceLink servers you own.
• "Create a token for an app" opens VoiceLink's own App tokens section, because tokens are always made in VoiceLink, where it confirms it's you first.
• If VoiceLink can't be reached, the page says so; your apps keep working.

Staying signed in

• With "Keep me signed in on this iPhone" on, the device stays signed in and renews quietly. For accounts with two-factor it asks for a code again after 30 days (the server owner can change this).
• Settings, Security, Devices lists connected devices, with "Disconnect This Device" and "Sign Out All Other Devices" (this device stays signed in).
• VoiceLink accounts can change their password in Settings, Security, Password. Other devices are signed out when it changes. Only accounts whose password really is managed by the Client Portal are sent there to change it.

Passkeys are not available yet.

🔑 Basic Authentication Setup