Authentication and Authorization

Authentication is the process of verifying the identity of a user. This usually involves a user providing some form of credentials (like a username and password) to a service, which then validates those credentials and provides a way to identify the user in future requests. This identity can be used to determine what data the user has access to (authorization).

Authentication

Triplit uses JWTs (opens in a new tab) to communicate user identity. Authentication (that is the validation that a user is who they say they are, and the generation of a JWT identifying the user) itself should be handled by an authentication service outside of Triplit. This could be a third-party service like Clerk (opens in a new tab), Auth0 (opens in a new tab), Firebase Auth (opens in a new tab), AWS Cognito (opens in a new tab), Supabase Auth (opens in a new tab), etc or a custom service built by your team.

The JWT will need to be signed with a proper signature. Triplit supports both symmetric (HS256) and asymmetric (RS256) encryption algorithms for JWTs. If you are using Triplit's hosted offering Triplit Cloud, then you will need to provide the JWT's signing secret or public key to Triplit in the External JWT secret field in your project's settings. If you are self-hosting Triplit, you will need to provide the signing secret or public key when you start the server with the EXTERNAL_JWT_SECRET environmental variable.

The JWT should usually have some user-identifying information (e.g. the sub claim (opens in a new tab)), which can be accessed by Triplit to handle access control that user. For backwards compatibility, Triplit reads the following claims:

x-triplit-user-id: The user's unique identifier. This is assigned to the variable $session.SESSION_USER_ID in queries.

Tokens

Triplit provides two basic tokens that are available in your project dashboard (opens in a new tab):

anon token: A token that represents an anonymous user. This token is safe to use on a client side device and should be used when no user is logged in.
service token: This token is used for administrative purposes and should only be used in trusted environments like a server you control. This token will bypass all access control checks.

When getting started with Triplit these are fine to use, but they don't specify which application user is accessing the database, or if they have a distinct access role. This information can be configured by providing a JWT with the proper claims and signature (see previous section). Triplit's flexible design allows you to define any JWT claims you would like.

Using your tokens

When you instantiate a TriplitClient, you can provide an initial token to authenticate with the server. This token is used to determine what data the client has access to.

import { TriplitClient } from '@triplit/client';
const client = new TriplitClient({
  token: '<your-token>',
  serverUrl: 'https://<project-id>.triplit.io',
});

This will automatically connect the client to the server and authenticate with the provided token. If you would like to connect manually, you can set autoConnect to false and call client.connect() when ready.

import { TriplitClient } from '@triplit/client';
const client = new TriplitClient({
  token: '<your-token>',
  serverUrl: 'https://<project-id>.triplit.io',
  autoConnect: false,
});
 
// Do other things
 
client.connect();

Modeling sign in and sign out flows

Starting sessions

If users in your app start in an unauthenticated state (e.g. you display a sign-in form when the app loads), or if users can sign out, you will need to use Triplit's sessions API to initiate and teardown sync connections and the appropriate moments. When changing users (as represented by tokens), you should use the startSession method.

async function onSignIn(token: string) {
  await client.startSession(token);
}

This will update the token and connect the client to the server. The TriplitClient calls this method implicitly when you provide a token to the constructor. For more information on the startSession method, see the Sessions API guide.

Ending sessions

When a user signs out, you should call the endSession method. This will disconnect the client and reset metadata related to the session. It will not clear any data stored in the client's cache. It's up to you, the developer, to decide whether or not the next user should have access to the data from the previous user.

async function onSignOut(clearCache: boolean = false) {
  await client.endSession();
  if (clearCache) {
    await client.clear();
  }
}

For more information on the endSession method, see the Sessions API guide.

Updating sessions

If your authentication provider issues short-lived tokens, you may need to refresh the token mid-session. Read more about refreshing a session in the Sessions API guide.

Authorization

Triplit allows you to define rules on your collections that determine who can read and write data. This is usually based on the tokens you provide. See permissions for more information on reading your tokens in queries and access control definitions.

Triplit Console Clerk