The master password system

BoothIQ has an emergency access system called the master password. It's a single-use code that lets a trusted party get into a fully-locked-out kiosk without a password reset. This article explains it from an operator's perspective.

Who this is for: Operators who need to understand what the master password is and how to use it in an emergency.

What it is

A master password is a single-use emergency code (format: EMR-*) that BoothIQ accepts in addition to your normal password. It's designed for one specific situation: you're locked out of the kiosk and you can't recover with the normal password or recovery PIN.

You can't generate a master password yourself on the kiosk. You have to obtain one from a trusted source. Typically:

  • BoothIQ support, who can issue a cloud-side emergency password
  • The HMAC mechanism described in the developer docs (advanced, usually only used by support technicians)

When to use it

Use the master password only when:

  1. You can't sign in with the regular password (forgot it, never knew it, or it was changed without your knowledge)
  2. You don't have a working recovery PIN
  3. You can't wait for an in-person service visit
  4. You're a legitimate operator, not someone trying to bypass security on a booth that isn't yours

Don't use the master password as a routine login alternative. It's intentionally cumbersome. Single use, requires contacting support, no convenience.

How to obtain a master password

Option A: Cloud-issued emergency password (EMR-*)

If your booth is registered to the BoothIQ cloud:

  1. Contact BoothIQ support by phone, email, or whatever channel your account uses.
  2. Verify your identity. Support will ask for details proving you own the booth. Your account email, the Booth ID, your business name, etc. They will not give out a master password to anyone who asks.
  3. Support issues a cloud emergency password from the cloud dashboard. The format is EMR- followed by some characters.
  4. Support tells you the password (probably over a secure channel. Phone, secure messaging, or email).
  5. You go to the kiosk and use the password.

Option B: HMAC-derived master password (advanced)

This is a deeper mechanism documented in the developer docs (docs/MASTER_PASSWORD.md). It uses a per-kiosk secret combined with a one-time code to derive a valid emergency password.

This path is for support technicians, not for routine operator use. If support tells you to use it, follow their exact instructions.

How to use a master password on the kiosk

  1. Go to the admin login screen on the kiosk (5-tap on the credits indicator).
  2. Enter your username (e.g. admin).
  3. Enter the master password in the password field. Type the EMR-* code exactly as support gave it to you.
  4. Tap Sign In.
  5. The booth validates the code and signs you in.

After you're in, immediately:

  • Change the regular password to something you know.
  • Reset the recovery PIN.
  • Sign out and sign back in with the new credentials to verify.

Single-use enforcement

The master password is single-use by design. Once it's been used:

  • The booth records the code as used in its local audit trail.
  • Trying to use the same code again will be rejected.
  • The booth also records when the code was used, by which username, and from what device.

This means you can't write down a master password "for later." Once it's been validated even once, it's burned.

Cloud-issued passwords expire

Cloud-issued EMR-* passwords are time-limited. Typically they expire within hours of being issued. Use them immediately when you receive them.

What the master password does NOT do

To prevent misuse:

  • It does not bypass the rate limiter completely. If you're brute-forcing master passwords, the booth still locks you out.
  • It does not unlock the cash box.
  • It does not modify other admin accounts on the booth.
  • It does not clear the audit logs.
  • It does not leave a "back door." It's a one-time emergency entry point, then it's gone.

What support sees

When support issues a master password to you, the issuance is recorded in the cloud:

  • Who requested it (your identity)
  • Which booth (Booth ID)
  • When it was issued
  • When it was used
  • (If it expires) When it expired

Support has an audit trail of every emergency password they've issued. This is for everyone's protection.

A walkthrough

Scenario: You forgot the admin password and the recovery PIN

  1. Don't power-cycle the kiosk repeatedly hoping it'll reset. Admin credentials are persistent.
  2. Don't try the same wrong password repeatedly. You'll get rate-limited.
  3. Take a deep breath and find your password manager (where the password should have been). If it's not there, accept that you forgot it.
  4. Contact BoothIQ support. Give them your Booth ID and explain the situation.
  5. Support verifies your identity (this may take a few minutes).
  6. Support issues an EMR-* cloud emergency password and tells you the code over a secure channel.
  7. You walk to the kiosk and go to the admin login screen.
  8. You type the username (admin) and the EMR-* code as the password.
  9. You sign in.
  10. You immediately open Settings → Security & Users → Change My Password and pick a new strong password.
  11. You immediately reset the recovery PIN.
  12. You store both in your password manager.
  13. You sign out and sign back in with the new password to verify.
  14. You document the incident so it doesn't happen again (e.g. write a note: "set up password manager for booth before opening").

Total time: depending on how fast support responds, this can take a while.

What to do if support can't help quickly

If you're locked out and support is unresponsive:

  • Take the booth out of customer service. Even if you can't manage it, you don't want it running unattended in a broken state.
  • If the booth still functions for customers (the welcome screen still works), you can keep it running until support gets back to you. You just can't make any admin-side changes.
  • Document the incident so you have a clear log of what happened and when.
  • Try a different support channel. Email, phone, the cloud dashboard's contact form.

After-incident hygiene

After every master password event, do a security review:

  1. Why did you get locked out? Forgot password? Forgot PIN? Brute force?
  2. What can you change to prevent it from happening again? Use a password manager? Keep PIN written down securely? Set up additional admin users?
  3. Did anyone unauthorized see the master password during use?
  4. Does support need any follow-up information about the incident?

Common questions

Can a competitor or attacker request a master password for my booth?

No. Support verifies the requester's identity against the cloud account that owns the booth. Random requests are rejected.

Can I store a master password in my password manager for emergencies?

No. They're single-use and time-limited. Storing one is pointless.

Can the master password be issued without the booth being registered to the cloud?

The cloud-issued path requires registration. The HMAC path (advanced) does not require cloud registration but is more complex. Contact support for offline scenarios.

Is the master password the same as the recovery PIN?

No. The recovery PIN is something you set up on first login to recover your own password. The master password is something support issues to you in an emergency.

Can I disable the master password system entirely?

No. It's a built-in part of BoothIQ. The trade-off is that an attacker would need to compromise both the cloud account and support's verification process to abuse it. Which is much harder than guessing a password.

Verify it worked

You've successfully recovered access when:

  • You can sign in to admin with a regular password again
  • You've reset your recovery PIN
  • You've stored the new credentials in a password manager
  • The master password you used can no longer be re-used

Next steps