How Magic Token Works

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:

Browser opens the link — URL contains a one-time or short-lived token
System verifies the token — checks validity and expiry
Session created — signs in and stores credentials in localStorage
Subsequent auto sign-in — so long as the token is valid, reopening the page signs you in automatically

Token Types

realvco uses two tokens:

Token	Purpose	Lifetime
Magic Link Token	First-time sign-in	24 hours
Session Token	Persistent signed-in state	30 days

Magic Link Token

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

Why Is Magic Token Secure?

“Sign in with one click” sounds risky, but there are layers of protection:

Mechanism	Description
HTTPS	Every link uses HTTPS; tokens are encrypted in transit
Unpredictable tokens	Cryptographically random; cannot be guessed
Short lifetime	Magic Links auto-expire after 24 hours
Single-use	Consumed tokens are invalidated
IP scoping	Tokens are bound to the first-use IP range to limit theft

Protecting Your Magic Link

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:

Copy it from the Admin Panel: once signed in, copy each companion’s Magic Link
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 today. For a forced sign-out:

Clear browser localStorage, or
Redeploy the container (new token; old ones are invalidated)

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.