SpacetimeDB modules are exposed to the open internet and anyone can connect to them. Therefore, authentication is a critical part of using SpacetimeDB securely.
SpacetimeDB uses OpenID Connect (OIDC) identity tokens for authentication, making it compatible with most OIDC providers (e.g., Auth0, Firebase, Clerk, Google, GitHub, Facebook, and many more). You can choose any OIDC provider that fits your needs, or even implement your own.
If you're new to OIDC, check out our blog post about OIDC to learn more about how OIDC works and why it's a great choice for authentication.
If a client connects without supplying a token, SpacetimeDB creates a new identity and returns a server-issued token for that identity. If you want later connections to keep using that same identity, persist that returned token and pass it back into the SDK on reconnect.
On platforms that can send an Authorization header during the WebSocket
handshake, the SDK can reuse that saved token directly. On platforms that cannot
set custom WebSocket headers, the SDK first exchanges the saved token for a
short-lived WebSocket token through
POST /v1/identity/websocket-token,
then sends only that short-lived token in the WebSocket URL.
This matters when you persist tokens on the client:
- Save the long-lived server-issued token that establishes the user's identity.
- Do not overwrite an already-saved long-lived token with a short-lived WebSocket token received during reconnect.
- Expect this distinction on browser-style transports where WebSocket headers are unavailable, such as Unity WebGL builds.
To make it easier to get started with authentication, SpacetimeDB offers SpacetimeAuth, a fully managed OIDC provider built specifically for SpacetimeDB applications. SpacetimeAuth handles user management, authentication flows, and token issuance, so you don't have to worry about building and maintaining your own authentication service.
SpacetimeAuth is meant to be simple to use and easy to integrate with SpacetimeDB. While being production-ready and able to support most common use cases, it is not as feature-rich as some third-party OIDC providers. If you need advanced features or customization, you may want to consider using a third-party OIDC provider instead.
You can also use any third-party OIDC provider with SpacetimeDB. Most OIDC providers offer similar features, such as user management, authentication flows, and token issuance. When choosing a third-party OIDC provider, consider factors such as ease of integration, pricing, scalability, and security.
- Auth0 A managed identity and access management service that provides, user management, and extensible login flows for applications and APIs.
- Clerk A developer-focused authentication and user management platform that provides OIDC-compliant sign-in, session management, and prebuilt UI components for modern web applications.
- Keycloak An open-source and self-hosted OIDC provider with extensive features, customization options and integrations.
Sometimes, you may need to authenticate your servers, APIs or other services that interact with your SpacetimeDB database. OIDC tokens can also be used for this purpose, allowing secure communication between your services and SpacetimeDB.
To authenticate your services, you have e few options depending on your OIDC provider:
- Client credentials flow: Many OIDC providers support the client credentials flow, which allows your service to obtain an access token using its own credentials (client ID and client secret). This is a common approach for service-to-service authentication.
- Service accounts: Some OIDC providers offer service accounts, which are special user accounts designed for non-human users (e.g., servers, APIs). You can create a service account and use its credentials to obtain an access token.
Obtaining an OIDC token is just the first step in securing your SpacetimeDB module, known as authentication. You also need to implement authorization to control what authenticated users can do within your module.
When a client connects to your SpacetimeDB module, the SpacetimeDB server validates the client's OIDC token and extracts the identity claims. These claims are then made available to your module's reducers, views and procedures via the context.
Check out the usage guide for more information on how to access and use authentication claims in your module: