← All docs
View on GitHub

Signing in & first-run — troubleshooting

This guide walks through signing in to VaultGuard from the Obsidian plugin for the first time, and fixes for the problems people hit most often. If you just need the happy path, see the Signing in for the first time section of the Setup Guide; this page goes deeper on each step and on errors.

VaultGuard never sends passwords by email. Any message that emails you a password is not from VaultGuard.

How you get access

You reach VaultGuard one of two ways:

  • You were invited. An organization admin adds your email and you receive an invitation email. It contains a Set your password button and an obsidian://vaultguard-invite?org=…&email=… deep link that pre-fills the plugin for you. There is no account until you set a password.
  • You created the organization. You signed up at vaultguard.cloud, which created your org and made you its first admin. Complete checkout, then sign in from the plugin.

Signing in from the plugin

  1. Click the VaultGuard shield icon in the ribbon (or run VaultGuard: Login from the command palette) and choose Login.
  2. Enter the details:
    • Organization slug — the short name your admin gave you (e.g. acme-corp). If you opened the plugin from an invite link, this is already filled in and hidden.
    • Email and Password. Use the eye icon in the password field to reveal what you typed if you're unsure.
  3. Click Sign in.

If your organization requires two-factor authentication, you'll be asked for a code next (see Two-factor authentication).

Setting your password (first time)

Invited users don't have a password yet. On first sign-in the plugin shows Set your password:

  1. Click Send reset code — a verification code is emailed to you.
  2. Enter the code and choose a password. Passwords need at least 12 characters with an uppercase letter, a lowercase letter, a number, and a symbol. A live checklist shows each requirement turning green as you type.
  3. Submit, then sign in with your new password.

If an admin created your account with a temporary password instead, the plugin detects this and shows the same set-a-new-password step inline — you don't need to contact anyone.

Two-factor authentication

If your org enforces 2FA, the first sign-in opens Set up two-factor authentication:

  1. Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.). Can't scan? Use Enter this secret manually and copy the code into the app by hand.
  2. Enter the 6-digit code from the app and click Verify & enable.
  3. Save your recovery codes. These one-time codes are the only way back in if you lose your authenticator. Copy them somewhere safe (a password manager), tick I have saved my recovery codes, then Done. You won't be shown them again.

On later sign-ins you'll just enter the current 6-digit code after your password.

Lost your authenticator

On the code prompt, choose Lost your authenticator? Use a recovery code, enter one of your saved recovery codes, then sign in again with your password — the plugin will walk you through setting up a new authenticator. If you've also lost your recovery codes, contact your organization admin; they can reset your 2FA. (For the at-rest encryption passphrase, recovery is different — see At-Rest Encryption.)

Connecting your vault

After signing in, each local Obsidian folder must be linked to one server-side vault:

  • One vault available — the plugin binds it automatically; you'll see a "bound to …" confirmation.
  • Several vaults — pick the one this folder should sync with.
  • No vaults yet — non-admins see a prompt to ask an admin for access (with a Contact your admin button) and a Retry once they've been added. Admins can create a vault on the spot.

Until a vault is bound, VaultGuard won't sync files or apply permissions — this is deliberate, and prevents same-named files in different vaults from colliding. See the Vault Model for the full picture.

Common problems

"Invalid email or password." The email or password is wrong, or the account doesn't exist yet. For security, VaultGuard doesn't say which. Double-check the email, use the eye icon to verify the password, or use Forgot password? to reset it. If you were invited but never set a password, use Set your password instead.

"Organization '…' not found. Check the slug and try again." The org slug is mistyped or isn't reachable from your configured server. Confirm the exact slug with your admin (it's lowercase, e.g. acme-corp, not the company's display name). If you were invited, reopen the invite link so the slug is filled in for you.

"The server rejected the connection…" / "…server is temporarily unavailable." A 401/403 usually means the slug or endpoint is wrong for this server; a 5xx means the server is briefly down — wait a moment and retry. If you self-host, check that your API endpoint in Settings → Connection is correct.

"Couldn't reach the server. Check your internet connection and the org slug." You're offline, or the API endpoint is unreachable. Confirm you have a connection and that the endpoint/slug are right.

Two-factor setup says I wasn't signed in. If you close or cancel the 2FA setup screen, VaultGuard doesn't sign you in — your account is untouched. Start the login again when you're ready to finish setting up your authenticator.

The login screen is stuck after I close a dialog. Close the login window and reopen it from the shield icon. No state is saved until you complete sign-in.

For anything else, your organization admin can see your account status and 2FA state from the web admin panel, and reset your password or 2FA if needed.