Skip to main content


Ditto does not come with an identity provider. Using "Online With Authentication" requires that that you have your own identity provider already set up. Each app can use multiple identity providers. Identity providers can be:

The "Online With Authentication" identity type is geared towards apps that will be deployed in real world settings. "Online With Authentication" identity types are:

  • for apps that need to integrate with existing permissions
  • for apps that need to integrate with existing authentication systems

How it works


Devices using Online with Authentication need to connect to the Internet and authenticate at least once before synchronizing with other peers. This is required so devices can get a valid certificate before going offline.

To use the "Online With Authentication" system, your client application is expected to authenticate with your identity system and retrieve some sort of token 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).

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 the 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:

sequenceDiagram Client App->>Your Authentication Mechanism: Send Credentials Your Authentication Mechanism->>Client App: Return JWT Client App->>Ditto Big Peer: JWT Ditto Big Peer->>Auth Webhook: JWT Auth Webhook->>Ditto Big Peer: Formatted Ditto Auth Response Ditto Big Peer->>Client App: Ditto Credentials rect rgba(0, 0, 255, .1) Client App->Ditto Big Peer: Ditto Sync end


Creating your client

Create the ditto client with the onlineWithAuthentication identity. This identity requires an authentication handler authHandler.


You must refresh the auth token when it expires. You can do that by implementing authenticationExpiringSoon. If you do not implement this, then sync will stop when the token expires.

import { init, Ditto } from "@dittolive/ditto"(async () => {  await init() // you need to call this at least once before using any of the Ditto API
  const authHandler = {    authenticationRequired: async function(authenticator) {      console.log("Login request.");    },    authenticationExpiringSoon: function(authenticator, secondsRemaining) {      console.log(`Auth token expiring in ${secondsRemaining} seconds`)    }  }
  const identity = {    type: 'onlineWithAuthentication',    appID: 'REPLACE_ME_WITH_YOUR_APP_ID',    authHandler  }
  const ditto = new Ditto(identity, '/persistence/file/path')  ditto.startSync()})()


Login takes two parameters: the first is token. The token can be any string value. Most auth services use a JWT (JSON Web Token), but you can send any token you want from the client. For example, during testing you may want to create a secret code for development use. This string will be sent in a POST request to the HTTP route.

Sample Authentication Webhook Endpoint in the Portal

let accessToken = await ThirdPartyAuth.getToken()await ditto.auth.loginWithToken(accessToken, 'my-auth')


Logout will stop sync, shut down all replication sessions, and remove any cached authentication credentials. Note that this does not remove any data from the store. If you wish to delete data from the store then use the optional cleanupFn parameter to perform any required cleanup.

The cleanupFn is an optional function that will be called with the relevant Ditto instance as the sole argument that allows you to perform any required cleanup of the store as part of the logout process.

async function cleanupFn (ditto) {  await'cars').findAll().evict()}await ditto.auth.logout(cleanupFn)