​
Online Authentication Mechanisms

The primary mechanisms that Ditto provides for authentication use Ditto Server as a central authentication server. This means that all new devices and users must first connect to Ditto Server to authenticate, prior to being able to join and sync data with the mesh.

​
Online Playground

Online Playground mode is Ditto’s authentication-light environment intended for development and testing, or use cases that do not require per-user permissioning. This allows developers to get a Ditto-enabled application up and running quickly with minimal setup. In this mode, devices connect through Ditto Server using a shared app ID and a Playground token, but without unique user authentication. Essentially, it’s a sandbox identity provided for convenience. Ditto Server automatically trusts any client that knows the correct app identifier and its corresponding Playground token. This token (obtainable from the Ditto portal for your app, see Getting SDK Connection Details) is used to authenticate your SDK to Ditto Server - i.e. it tells the cloud “I belong to application X and I can prove it as I know the password”. Every instance of your app uses the same token. Once the token and app ID are presented, the client can join the cloud-backed mesh and start syncing. There are no user names or passwords; the authentication is a single shared token (hence “Playground”). This makes it extremely easy to connect multiple devices and see data sync in action. The Online Playground identity is meant for quick experimentation and prototyping. It lets teams explore Ditto platform features and functionality without the overhead of setting up a custom auth server or user management. Great use cases include proof-of-concept apps, hackathons, or early development stages where you want to focus on core application logic and test syncing, rather than dealing with authentication infrastructure. It’s also useful for demos or tutorials - for instance, spinning up a sample app where everyone uses the same token to join a shared data set. Playground mode deliberately offers limited security for easy development and is not recommended for production. As the token is shared and static, it functions more like an API key that is the same for all clients. Anyone in possession of the token can connect and fully access the data. There is no concept of user-level permissions in this mode; all connected clients can read and write all data in the collections for that app. For production or any sensitive data, you’ll want to switch to a more secure authentication method.
Playground has no individual identities, authorization within the app is essentially all-or-nothing. Every connected device has the same capabilities. If your use case requires certain clients to have read-only access or other restrictions, Playground cannot enforce that, use Online with Authentication instead.

​
Online with Authentication

Online with Authentication is Ditto’s recommended authentication mode for Production. Unlike Online Playground, this mode integrates with real user identities or device credentials. Each client must log in to the Ditto network, and only upon successful authentication is it allowed to sync data with the cloud or peers. This approach is suitable for apps in real world situations where not every device is implicitly trusted — it enables you to verify who is connecting, and control what each client can do. In Online with Authentication, the Ditto Server acts as a gatekeeper and coordinates the auth process. To use the “Online with Authentication” system, your client application is expected to authenticate with your identity system and retrieve a secret token (it can be any arbitrary string) prior to syncing with Ditto. Often times this token is some sort of identity token, access token, commonly in the format of a JWT (JSON Web Token). You can use an existing identity provider (e.g. Auth0, Clerk) or implement your own custom authentication mechanism, and as expected, you are responsible for the security of this token generation/passing aspect. Once your client application successfully has retrieved this token, it should pass it to the Ditto authenticator which will pass it to an authentication webhook. As the developer, you are responsible for writing code and deploying this webhook to an accessible URL. The authentication webhook will validate and decode the token from the client side and return identity and access control information back to your Ditto instance. The full flow is detailed in the diagram below:
You can follow the Online with Authentication tutorial to learn how to use the Online with Authentication identity.

​
User Permissions

A major benefit of Online with Authentication is that each user or device is distinct, which allows for fine-grained authorization rules. Since the user permissions are centrally managed in this mode, your authentication server can decide what each authenticated identity is allowed to do. These permissions are expressed on each collection in the form of queries, for example:
To prevent users being able to “hijack” documents they should not have access to when using peer-to-peer replication, Ditto enforces that permissions can only be specified on the immutable _id field of a document. You should ensure that you model your data so that all of the fields that you want to control access to are part of the _id field.
This means you could have viewer roles that only sync down data but cannot make edits, while admin roles have full read-write capabilities. All such rules are enforced by both Ditto Server and all devices participating in sync in the mesh. If a client tries to synchronize a document it isn’t authorized for, the document will not be synchronized. Moreover, because authentication is individual, you can set a single user’s permissions without affecting others. This granular control is essential for multi-user applications and aligns with typical enterprise security requirements. You can read more about how to appropriately authorize users in Authorizing Users.

​
Detailed Online Certificate Flow

Both online mechanisms follow the same basic flow, though they differ in how the supplied credentials are validated.
1

Complete a Peer Key Challenge

The peer’s public key will be included in the certificates returned by the identity service. The identity service needs proof that the authenticating Small Peer actually holds the corresponding private key.
  1. Small Peer downloads a challenge token from /_ditto/auth/cert - this is a time-limited JWT which the client treats as opaque data.
  2. Small Peer uses their Peer Key to sign it.
2

Log in with Credentials

When a client attempts to authenticate, it will make an HTTPS request to the identity service containing the following payload:
  • Signed challenge
  • App ID
  • Provider name
  • Credentials to be forwarded to the app’s webhook handler
Once the identity service has a response from the auth webhook, it will build and sign the required Ditto Credentials (including a JWT and an X.509 certificate) and send them back down to the client. The response will include the client’s generated certificate and private key, a list of CA certificates the client should trust, and a DateTime for expiration. The client will persist the JWT, device private key, device certificate, and CA certificates on disk and only update them when they get near expiration.When two peers authenticate with each other, they can use either the JWT or the device certificate via MTLS. The decision depends on the client’s capabilities and connection type.

​
Offline Shared Key

Shared Key authentication in Ditto is a simple, pre-shared secret model. It offers an intermediate level of security for scenarios where all devices and users are inherently trusted. In this mode, every peer (device) in the Ditto network is configured with the same secret key. As long as a device knows the shared key, it is considered authenticated and can join the network. All participants share a single secret cryptographic key that identifies the group. If a device presents the correct key, Ditto trusts it as an authenticated peer. In effect, any device is trusted provided they know the shared key. There is no central server verifying identities - trust is entirely based on possession of the shared secret. This makes setup straightforward (no user accounts or token exchanges are needed). Communication is encrypted using TLS 1.3 and peer identities are verified using certificates. This is the same state-of-the-art technology used in web browsers. It applies across all transports, from Bluetooth to WiFi. Each device issues a self-signed TLS certificate using the supplied private key. Peers then only trust peers whose certificates are signed by the same key. In other words, Shared Key uses regular TLS security, except everybody is the CA. Shared Key mode is designed for closed, controlled environments. For example, an enterprise might use it on a fleet of devices that are centrally managed and not connected to the Internet. It’s suitable for offline or air-gapped deployments - such as on airplanes or on ships. In such cases, the shared key provides a quick way for devices to recognize each other and sync data without any cloud service. This mode assumes a high level of pre-existing trust. It is only suitable for private apps where users and devices are both trusted to perform any actions. All devices effectively have the same access rights, because they authenticate with the same credentials. There is no user-level differentiation – if you have the key, you have full read/write access to the data. Therefore, protecting the shared key is critical. If it were leaked or stolen, an unauthorized device could join and gain equal access. There’s also no way to revoke a single device’s access (short of changing the key for all devices). It is recommended that you should only use Shared Key when key distribution can be tightly controlled via a mechanism like MDM, and when the convenience of offline operation outweighs the lack of granular security controls. In general, we recommend using online authentication for any internet-connected or user-centric application.
If you have a use-case where you cannot use online authentication, but wish to use per-device permissions, then you can setup a self-managed authentication server.Please get in touch with us if you’d like assistance in setting up a self-managed authentication server.