realvco Docs

How Magic Token Works

Which Magic Token does this page cover?

There are actually two different “Magic Link / Token” mechanisms in realvco — they get mixed up often:

NamePurposeMechanismCovered here?
mVPS Admin Panel Magic TokenClick an Email link to enter the Admin Panel on your own mVPSURL with #token=xxx + 30-day Cookie✅ This page
realvco.com Account Magic LinkSign in to the realvco.com account portalhttpOnly Cookie + CSRF protection❌ See account/login

Quick rule of thumb: “into your own host” = first one; “into the realvco website” = second one.

What Is a Magic Token?

Magic Token is the simplified sign-in mechanism for realvco’s mVPS. Traditional passwords force you to memorize strings; Magic Token lets you sign in by clicking one link.

Mechanics

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Email     │────>│  Magic Link │────>│  Auto       │
│   link      │     │ (with token)│     │  sign-in    │
└─────────────┘     └─────────────┘     └─────────────┘

Clicking a Magic Link triggers:

  1. Browser opens the link — URL contains a one-time or short-lived token
  2. System verifies the token — checks validity and expiry
  3. Session created — signs you in and stores credentials in a Cookie that survives closing the browser (technically an httpOnly Cookie that page JavaScript cannot read, which prevents script-injection theft)
  4. Subsequent auto sign-in — so long as the Cookie is valid, reopening the page signs you in automatically

Token Types

realvco uses two tokens:

TokenPurposeLifetime
Magic Link TokenFirst-time sign-in24 hours
Session TokenPersistent signed-in state30 days
  • Arrives in the welcome email
  • Embedded in the Admin Panel and AI companion URLs
  • Single-use — invalidated after consumption
  • Expires after 24 hours

Session Token

  • Stored in the browser after a successful sign-in
  • Reopening the URL signs in automatically
  • Expires after 30 days of inactivity
  • Clearing browser data requires a new Magic Link

Security Considerations

Sign in With One Click — Won’t It Get Stolen?

This is the question we hear most often. Several layers protect you:

MechanismDescription
HTTPSEvery link uses HTTPS; tokens are encrypted in transit
Unpredictable tokensCryptographically random; cannot be guessed
Short lifetimeMagic Links auto-expire after 24 hours
Single-useConsumed tokens are invalidated
IP scopingTokens are bound to the first-use IP range to limit theft

Important:

  • Do not share your Magic Link with anyone you do not fully trust
  • Do not post publicly (forums, GitHub, social media)
  • Review sign-in history periodically in the Admin Panel
  • If you suspect a leak, redeploy the container to issue a new token

FAQ

Q: I Lost the Magic Link — Now What?

Two options:

  1. Copy it from the Admin Panel: once signed in, copy each companion’s Magic Link
  2. Contact support: with proof of purchase, the welcome email can be resent

Q: Can I Use It on Multiple Devices?

Yes. A Magic Link works across devices — each establishes an independent Session Token.

Q: What if I Clear My Browser Data?

You’ll need the original Magic Link again. Store the welcome email somewhere safe.

Q: How Do I Sign Out?

There is no explicit sign-out button today. For a forced sign-out:

  1. Clear the browser Cookie for your host URL (browser settings → Privacy → Clear data for a specific site)
  2. Or redeploy the container (issues new tokens; all old ones are invalidated)

The Cookie is httpOnly, which means it can only be cleared via browser settings — page JavaScript cannot clear it for you. This is intentional security (it prevents malicious scripts from stealing your sign-in state), but the trade-off is no “click here to sign out” button. If you’re unsure how to navigate browser settings, the simplest path is option 2 — redeploy the container, which rotates the entire token pool and invalidates everything old.

Technical Details (for the Curious)

Tokens use the JWT (JSON Web Token) format:

Header: { "alg": "HS256", "typ": "JWT" }
Payload: {
  "sub": "container_id",
  "iat": 1234567890,
  "exp": 1234654290,
  "role": "admin"
}
Signature: HMACSHA256(base64(header) + "." + base64(payload), secret)

The token is verified on the host — it cannot be forged.