Skip to main content

Online with Authentication

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
  • The Ditto platform 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:
    • Your own service
    • Facebook, Twitter, GitHub, etc...
    • Okta, Auth0, Stytch, etc...

For a more thorough walkthrough, see the tutorial.

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

Example of authentication with Facebook and an iOS app with Ditto

Let's say you're using something like Facebook authentication to identity users in Your App.

Typically, an iOS application would use the Facebook SDK to login and retrieve a Facebook access token. When the Facebook SDK logs in it'll retrieve this access token which you can pass to the Ditto flow. Ditto's Big Peer will forward it to an Auth WebHook which is an HTTP endpoint where you can write your own logic. This Auth WebHook HTTP endpoint needs to respond with JSON that describe the user's identity and the permissions.

sequenceDiagram Your App->>Facebook SDK: Send Credentials Facebook SDK->>Your App: Return Facebook Access Token Your App->>Ditto Big Peer: Send Facebook Access Token Note over Ditto Big Peer,Auth Webhook: Ditto Big Peer simply forwards the Facebook Access Token from your app to a registered webhook Ditto Big Peer->>Auth Webhook: Forwards Facebook Access Token Note over Auth Webhook,Ditto Big Peer: Your auth webhook logic is code that you write and can decide to give Auth Webhook->>Ditto Big Peer: Auth webhook validates and returns a formatted Ditto Auth Response Ditto Big Peer->>Your App: Ditto Credentials Your App->Ditto Big Peer: Ditto can begin sync with Ditto Big Peer

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)