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 Replyke without requiring users to create a separate Replyke account. Your backend signs a JWT with a project-specific private key; the SDK exchanges that JWT for Replyke 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 Replyke 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. Replyke verifies the signature, looks up or creates the user, and returns Replyke access and refresh tokens.
3

The user is authenticated

From this point, the user is signed into Replyke 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 Replyke)
issYour Replyke 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, Replyke 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("replyke-private-key.pem");

function createReplykeJwt(userId: string, userData: object) {
  return jwt.sign(
    {
      sub: userId,
      iss: "your-replyke-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 ReplykeProvider (or ReplykeIntegrationProvider 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 { ReplykeProvider } from "@replyke/react-js";

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

  return (
    <ReplykeProvider projectId="your-project-id" signedToken={signedToken}>
      <YourApp />
    </ReplykeProvider>
  );
}
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, Replyke 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