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 authentication service should provide a way to generate a token with Triplit specific claims that can be used to identify the user.

A token must have the following claims:

{
  "x-triplit-project-id": "<your-project-id>",
  "x-triplit-token-type": "external"
}

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.

As well, the JWT will need to be signed with a proper signature. If you are using Triplit's hosted offering Triplit Cloud, then you will need to provide the signing secret of your JWT 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 to Triplit when you start the server via an environment variable EXTERNAL_JWT_SECRET.

Tokens

When connecting to a Triplit server, you can provide identification information by passing in a token to your Triplit Client. 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>',
});

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.

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.