Skip to main content
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

1

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.
2

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.
3

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:
ClaimDescription
subThe user’s ID in your system (becomes foreignId in Sublay)
issYour Sublay project ID
userDataObject 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.
FieldTypeDescription
emailstringUser’s email address
namestringDisplay name
usernamestringUnique username within the project
avatarstringURL of avatar image
biostringShort bio text
locationobject{ latitude, longitude }
birthdatestringISO 8601 date string
metadataobjectPublic custom data
secureMetadataobjectPrivate 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>
  );
}
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.

​
See Also