Guest Mode

Learn how to implement guest authentication in your application

Guest accounts allow users to immediately start using your application without going through a full registration process. This feature is particularly useful for applications where you want to reduce friction in the user onboarding process.

Key Features#

They are locally persisted, so guest users can leave and return to the same account on the same device.
Locally persisted sessions.
Fully functional embedded wallets.
Upgradeable to fully logged-in accounts.
They can be logged out and deleted as needed.

User data and embedded wallets from guest sessions cannot be merged into an existing user account — guest accounts can only be upgraded into a new user account. If a guest user wants to log in with an existing account, you must delete the guest user session first.

Implementation#

Create a guest account (client-side)#

Use the registerGuest method from the Openfort SDK to create a guest account:

import openfort from "./openfortConfig";
async function handleGuest() {
  try {
    const data = await openfort.registerGuest();
    // Handle successful guest registration
    // The response includes player information and authentication tokens
  } catch (error) {
    // Handle error
  }
}

Upon successful registration, you'll receive a response containing the player information and authentication tokens:

{
  "player": {
    "id": "pla_...",
    "object": "player",
    "createdAt": 1234567890,
    "linkedAccounts": []
  },
  "token": "eyJhbG...",
  "refreshToken": "eyJhbG..."
}

integration tip

Display guest access alongside normal login options
Use clear labeling to distinguish between guest and full account creation

const LoginOptions = () => {
  return (
    <div className="space-y-4">
      <Button onClick={handleGuest}>
        Continue as Guest
      </Button>
      <Button onClick={() => router.push("/login")}>
        Login or Create Account
      </Button>
    </div>
  );
};

Upgrade a guest user to a logged-in user#

Simply call link method to enable the guest user to upgrade their account to a logged-in account using any authentication method of their choice.

Example Implementation#

Here's a complete example of a guest authentication flow:

import openfort from "./openfortConfig";
import { useRouter } from "next/router";
import { useState } from "react";
function GuestAuth() {
  const router = useRouter();
  const [status, setStatus] = useState(null);
  const handleGuest = async () => {
    setStatus({
      type: "loading",
      title: "Creating guest account...",
    });
    try {
      const data = await openfort.registerGuest();
      
      setStatus({
        type: "success",
        title: "Guest account created",
      });
      
      // Store credentials and redirect
      openfort.storeCredentials({
        player: data.player.id,
        accessToken: data.token,
        refreshToken: data.refreshToken,
      });
      
      router.push("/");
    } catch (error) {
      setStatus({
        type: "error",
        title: "Error creating guest account",
      });
    }
  };
  return (
    <div>
      <Button onClick={handleGuest}>
        {status?.type === "loading" ? (
          <Loading />
        ) : (
          "Continue as Guest"
        )}
      </Button>
    </div>
  );
}