External Auth

If you already have a user authentication system (such as Clerk, Auth0, Firebase Auth, or your own backend), you can integrate it with Sublay without requiring users to create a separate Sublay account. Your backend signs a JWT with a project-specific private key; the SDK exchanges that JWT for Sublay tokens.

How It Works

Your backend signs a JWT

After your own auth system verifies the user, your server signs a JWT using your Sublay project’s RSA private key. The token identifies the user by their ID in your system.

The SDK exchanges the JWT

Call verifyExternalUser (available via the useAuth hook or directly) with the signed JWT. Sublay verifies the signature, looks up or creates the user, and returns Sublay access and refresh tokens.

The user is authenticated

From this point, the user is signed into Sublay and all SDK hooks work normally. Token refresh is handled automatically.

JWT Requirements

Your backend must sign the JWT using RS256 (RSA 256-bit) with your project’s private key. The payload must include:

Claim	Description
`sub`	The user’s ID in your system (becomes `foreignId` in Sublay)
`iss`	Your Sublay project ID
`userData`	Object with optional profile fields (see below)

`userData` fields

All fields in userData are optional. If a user already exists and any field has changed, Sublay updates the stored value.

Field	Type	Description
`email`	`string`	User’s email address
`name`	`string`	Display name
`username`	`string`	Unique username within the project
`avatar`	`string`	URL of avatar image
`bio`	`string`	Short bio text
`location`	object	`{ latitude, longitude }`
`birthdate`	`string`	ISO 8601 date string
`metadata`	object	Public custom data
`secureMetadata`	object	Private custom data

Backend Example (Node.js)

import jwt from "jsonwebtoken";
import fs from "fs";

const privateKey = fs.readFileSync("sublay-private-key.pem");

function createSublayJwt(userId: string, userData: object) {
  return jwt.sign(
    {
      sub: userId,
      iss: "your-sublay-project-id",
      userData,
    },
    privateKey,
    { algorithm: "RS256", expiresIn: "5m" }
  );
}

Keep your RSA private key on your server. Never expose it to the client. The JWT should be generated server-side and passed to the frontend at sign-in time.

Frontend Integration

Pass the signed JWT directly to SublayProvider (or SublayIntegrationProvider if you manage your own Redux store) via the signedToken prop. The SDK exchanges the token automatically on initialization — no manual API calls required.

import { SublayProvider } from "@sublay/react-js";

function App() {
  // Fetch or derive the signed JWT from your own auth system
  const signedToken = useMyAuthSystem().sublayJwt;

  return (
    <SublayProvider projectId="your-project-id" signedToken={signedToken}>
      <YourApp />
    </SublayProvider>
  );
}

import { SublayIntegrationProvider } from "@sublay/react-js";

function App() {
  // Fetch or derive the signed JWT from your own auth system
  const signedToken = useMyAuthSystem().sublayJwt;

  return (
    <Provider store={yourStore}>
      <SublayIntegrationProvider projectId="your-project-id" signedToken={signedToken}>
        <YourApp />
      </SublayIntegrationProvider>
    </Provider>
  );
}

Whenever signedToken changes (e.g., after a new user signs in), the SDK re-initializes auth with the updated token automatically.

The verify-external-user exchange happens inside the provider — you never need to call the endpoint manually. The provider creates the user if they do not exist, updates their profile if any userData fields have changed, and handles token refresh from that point forward.

User Identity

When a user signs in via external auth, Sublay stores the sub claim as foreignId on the user record and creates a UserIdentity entry with provider: "external". On subsequent sign-ins, the user is looked up by identity first, then by foreignId as a fallback, then by email.

Setup

Authentication

Users

Entities

Entity Lists

Comments

Reactions

Spaces

Events

Chat

Collections

Relationships

App Notifications

Push Notifications

Search & AI

Storage

Moderation

Custom Tables

How It Works

JWT Requirements

`userData` fields

Backend Example (Node.js)

Frontend Integration

User Identity

See Also

​How It Works

​JWT Requirements

​userData fields

​Backend Example (Node.js)

​Frontend Integration

​User Identity

​See Also

How It Works

JWT Requirements

`userData` fields

Backend Example (Node.js)

Frontend Integration

User Identity

See Also