Skip to content

Add description of default Auth (not SpacetimeAuth/OIDC) to Docs/Authentication #5079

Closed

Description

@SCHMUGGLERT

This issue is a result of a conversation on Discord in the unity channel.

Problem: It is unclear how the default server-issued JWT tokens work. That is, for platforms the server (tested on standalone) issues after a first connection a JWT with an expiration date of a minute, while for other platforms the initial JWT with no expiration date is returned upon connection success.

Here's what phoebe said on Discord to explain it:

On certain platforms, rather than directly passing the token you provide to withToken along to the SpacetimeDB WebSocket route, there's an intermediate step: we use that token to authenticate with SpacetimeDB via a non-WebSocket HTTP route, which returns a short-lived token, and then we pass that short-lived token to initiate the WebSocket connection. This is because some platforms' WebSocket libraries don't allow passing Authorization headers, meaning we have to pass the token in a query parameter in the URL of the new connection, and we very much do not want to do that with the long-lived access token. On platforms where the WebSocket library allows it, we just pass the long-lived token directly as an Authorization header, since those get encrypted by HTTPS.
The punchline being that you should not overwrite the long-lived token with the short-lived token when you reconnect with a previous server-issued token.

This by itself doesn't pose a problem, however if you build a project inspired by the Unity Tutorial and export it to web, it will cause a problem: The save token logic will override the long-lived token with the short-lived token, breaking that Identity.

Therefore I'd suggest the following additions to the docs:

  • Add a section to the Authentication docs that is dedicated to explain how the default server issued token work and/or login work and list the affected platforms for which an alternative implementation would be required.
  • Add a note to any code block that implements the client side token saving on the affected platforms or in general any affected platform, that an alternative implementation is required if keeping the Identity is desired. (e.g. Unity Tutorial Part 2 at the script block of GameManager, since Unity Web builds are affected)

Activity

  1. bfops commented on May 21, 2026

    @bfops
    Collaborator

    Hey @SCHMUGGLERT! Thank you for filing this.

    What do you think of these changes? https://github.com/clockworklabs/SpacetimeDB/pull/5085/changes

  2. SCHMUGGLERT commented on May 21, 2026

    @SCHMUGGLERT
    Author

    Assuming that all affected platorms are mentioned with the sentence

    Expect this distinction on browser-style transports where WebSocket headers are unavailable, such as Unity WebGL builds.

    LGTM

  3. linked a pull request that will close this issuedocs: consolidate outstanding docs fixes #5166on Jun 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions