Photon Fusion ConnectionToken vs Custom Auth (2026)

This distinction matters because a lot of Fusion examples, and the previous version of this guide, blurred two separate trust boundaries. The result is easy to spot in broken integrations: a developer tries to squeeze a backend JWT into ConnectionToken, expects Photon Custom Auth to receive it automatically, and then expects Custom Auth response data to appear inside server spawn callbacks.

That is not how Fusion 2 is shaped. This guide separates the three jobs you actually have to solve: account identity, session admission, and durable player data.

ConnectionToken vs AuthValues: two different paths

Mechanism	Who consumes it?	Best use	What not to put there
StartGameArgs.ConnectionToken	Your Fusion Host/Server authority	Short match admission, reconnect ownership, password-like/session-specific proof	Full player profile, inventory, ordinary backend JWTs
StartGameArgs.AuthValues	Photon Cloud → your configured Custom Authentication provider	Account authentication and a stable Photon UserId	Large durable game state
Session properties	Photon matchmaking/session discovery	Searchable or session-level matchmaking metadata	Secrets, private player data
Your game backend	Trusted game/client/server code according to your API policy	Accounts, progression, inventory, economy, durable results	Per-tick realtime simulation state

Photon's current Fusion API describes ConnectionToken as a byte[] sent by the client to the server and notes that it is not used in Shared Mode. The authority can inspect the connection request token and can later obtain the player's connection token from the NetworkRunner.

About the widely cited 128-byte ConnectionToken limit

You will see Fusion integrations document a 128-byte ConnectionToken ceiling. Unisave, for example, documents that limit explicitly. Photon’s current public StartGameArgs API reference documents the field as byte[] but does not state the maximum on that reference page.

So treat 128 bytes as a compatibility ceiling to regression-test against your exact Fusion version, not as an excuse to build an undocumented binary profile format. The design conclusion is the same either way: keep this field short and purpose-specific.

A normal Crux player access token is far larger than 128 bytes and should not be used as a Fusion ConnectionToken anyway. It proves account identity to the backend; a Fusion connection token is better used as a short admission credential for one session.

A safe StartGame shape

If you use both Photon Custom Authentication and a Host/Server connection token, set them independently:

var auth = new AuthenticationValues();
auth.AuthType = CustomAuthenticationType.Custom;
auth.AddAuthParameter("build", buildId);
// Add the auth material your Custom Authentication provider expects.

var result = await runner.StartGame(new StartGameArgs
{
    GameMode = GameMode.Client,
    SessionName = sessionName,
    AuthValues = auth,
    ConnectionToken = shortAdmissionToken
});

AuthValues are for the Photon Cloud authentication path. ConnectionToken is for the Fusion authority that receives the connection. They may be related by your application logic, but Fusion does not magically transform one into the other.

What happens on the server/host side

In a Host/Server topology, the authority receives the application-defined token in the connection request. Treat it as untrusted bytes until you validate it. A useful admission token is usually:

• short-lived;
• opaque rather than containing the player's full profile;
• bound to a player and target session/match;
• single-use or replay-resistant when the threat model requires it; and
• validated before the player receives gameplay authority.

Fusion also exposes the connection token back to the server for a connected player. That makes it useful for application-defined reconnect/admission identity, but it still does not replace your durable account database.

Photon Custom Authentication: the actual response contract

Custom Authentication is configured in the Photon dashboard. The client supplies custom authentication values; Photon Cloud calls the configured authentication service and uses its response to continue, reject, or defer authentication.

The important ResultCode values are:

• 1: authentication successful.
• 0: authentication is incomplete/intermediate. This is not the ordinary success code.
• 2: credentials are wrong.
• 3: parameters are invalid.

A successful response can establish a stable UserId and may include fields such as Nickname, Data, and AuthCookie. Do not treat them as interchangeable:

• Data is custom authentication response data exposed through Photon's authentication response path. Keep it compact and respect Photon's supported-type restrictions.
• AuthCookie is deliberately not exposed to the client. Photon can carry it into server-side integrations such as Webhooks/WebRPC.
• UserId should be the stable verified identity you want Photon to use, not a client-invented account id.

Photon recommends configuring static query-string parameters in the dashboard when your auth service needs a shared origin/configuration check. Do not assume Photon sends a magic signing header unless you have implemented and documented a separate verification mechanism yourself.

Do not make AuthData your player database

Custom Authentication response data is useful for compact connection-time context, but it is not a replacement for durable player state. If your authoritative server needs inventory, progression, entitlements, moderation state, or economy data, load those from the backend under a verified player identity.

The most robust split is:

1. authenticate the account and obtain a stable backend player id;
2. establish the Photon UserId from that verified identity;
3. if Host/Server admission needs another proof, mint a short session-bound token for ConnectionToken;
4. load durable state from the backend after admission; and
5. write trusted match results from server-side code, not from a client-supplied profile blob.

Using Crux beside Fusion

Crux does not currently expose a drop-in Photon Custom Authentication callback, and it does not mint a Fusion-specific 128-byte join ticket. The integration should not pretend otherwise.

There are two honest ways to combine the products today:

Option A: use Crux for identity/data beside Fusion

Your game logs the player into Crux (guest/email, Google/GitHub/Discord OAuth, or native Steam ticket authentication), receives the normal Crux player token, and uses Crux for durable player data. Fusion continues to handle networking/session topology. If you do not need Photon Custom Authentication, that is enough.

Option B: put a small adapter behind Photon Custom Auth

If you want Photon Custom Authentication to establish the same player identity, host a small adapter service. It receives the auth material you chose to send through AuthValues, validates the Crux player token online using GET /v1/auth/me (or the trusted JS SDK verifyPlayerToken() helper), then returns the verified Crux player_id as Photon’s stable UserId.

If your dedicated Fusion server also needs per-match admission, mint a separate short-lived opaque ticket in your adapter/game service and use that as ConnectionToken. Crux does not currently issue that Photon-specific ticket for you.

Failure handling

Keep failure semantics explicit instead of relying on undocumented retry behavior:

• Invalid/expired identity: reject authentication and make the client re-authenticate.
• Invalid match admission: reject the Host/Server connection before gameplay authority is granted.
• Auth service unavailable: fail closed for protected sessions and let your client apply its own bounded retry/backoff UX.
• Heavy profile service unavailable: decide whether your game can enter a degraded mode or must block before the authoritative server mutates durable state.

Do not build around a made-up Photon timeout, retry count, or signing-header contract. Measure your own endpoint latency, keep the auth path small, and test the failure modes against the Fusion version you ship.

Related reading

• Photon + Crux integration hub
• Photon Fusion dedicated-server architecture
• Photon Fusion pricing and CCU billing
• Player authentication patterns
• Crux Unity SDK quickstart