Skip to main content
This guide explains how to authenticate users directly into Nudj using JWT tokens that encode user metadata. Use this when your users are already authenticated in your system and you want to pass them into Nudj seamlessly.
Use this method if: Users are already logged into your platform and you want to continue their session in Nudj without showing a login screen.If users arrive at Nudj directly to log in, use OAuth Integration Setup instead.

Quick Start

  1. Get your clientId and clientSecret from Nudj API Configuration
  2. Generate a signed JWT containing user details using your clientSecret
  3. Build the auto-login URL with the token and clientId
  4. Redirect the user to that URL
  5. They land in Nudj fully signed in

When to Use This Method

Use API Link if:
  • Users are already authenticated in your platform
  • You want to pass them into Nudj without showing a login screen
  • You’re embedding Nudj in your app or redirecting from your dashboard
  • You want the fastest, most seamless user experience
Don’t use this if users arrive at Nudj directly without being authenticated—in that case, use OAuth Integration Setup.

Retrieve Your Credentials

  1. Log into your Nudj admin panel
  2. Navigate to Organisation Settings → API Configuration
  3. Copy these values:
    • Client ID
    • Client Secret
You’ll need these to sign tokens and identify your organization.

Generate the User Token

The user token is a JWT (JSON Web Token) signed with your clientSecret. It must contain these properties:
import { sign } from "jsonwebtoken";

const userData = {
  userId: "abc123",              // ✅ REQUIRED: Unique ID for this user
  email: "[email protected]",     // ⚠️ Optional but recommended
  locale: "en",                  // ✅ REQUIRED: Language code (e.g., "en", "fr", "es")
};

function signUserToken(input) {
  const clientSecret = "YOUR_CLIENT_SECRET"; // From API Configuration
  return sign(input, clientSecret, { expiresIn: "1h" });
}

const userToken = signUserToken(userData);
console.log("Generated token:", userToken);

Token Properties

PropertyRequired?Description
userId✅ YesUnique identifier for the user. Stored as externalId in Nudj.
email⚠️ OptionalUser’s email address. Must be unique per user. If omitted, Nudj generates a placeholder email and the user can only log in via direct links.
locale✅ YesLanguage/region code (e.g., “en”, “fr”, “es”). Defaults to “en” if not provided.
username⚠️ OptionalDisplay name shown in Nudj UI. Defaults to “anonymous” until updated.
anonymousAccountId⚠️ OptionalProvided by Nudj to merge an anonymous session with the user’s account.

Auto-Sign the User Into Nudj

Once you have the userToken, build the login URL:
const domain = "loyalty.mycompany.com";     // Your Nudj domain
const clientId = "YOUR_CLIENT_ID";          // From API Configuration
const userToken = "YOUR_GENERATED_TOKEN";   // From previous step

const linkUrl = `https://${domain}/api/link?userToken=${userToken}&clientId=${clientId}`;

// Redirect the user to this URL
window.location.href = linkUrl;
The user will be redirected to Nudj and automatically logged in.

How It Works

Account Identification

Each user is identified by their userId. If a user with that userId already exists, their record is updated. If not, a new account is created.

Account Creation

When a new user arrives with an API Link token:
  1. Nudj checks if a user with that userId already exists
  2. If not, creates a new account with the provided details
  3. The user is logged in immediately

Account Updates

If a user logs in again with updated information (different email, locale, username):
  • Nudj updates the existing user record with the new values
  • The user’s existing data and history are preserved

Email Handling

  • If email is provided: Nudj uses it to identify and email the user
  • If email is omitted: Nudj generates a placeholder email; the user can only log in via direct links (no magic link or self-serve login)

Example Integration Flow

Here’s a complete example of how API Link authentication flows:
1

User logs into your platform

Your user authenticates with your system (however you handle that)
2

Backend generates token

Your backend code signs a JWT with the user’s details using your clientSecret
3

Frontend builds the link

Your frontend creates the login URL with the token and clientId
4

User is redirected

Your frontend redirects the user to the Nudj login URL
5

User lands in Nudj authenticated

Nudj verifies the token, creates/updates the user, and logs them in—no login screen shown

Code Example: Node.js Backend

const express = require("express");
const { sign } = require("jsonwebtoken");
const app = express();

// These come from your Nudj API Configuration
const NUDJ_CLIENT_ID = "your_client_id";
const NUDJ_CLIENT_SECRET = "your_client_secret";
const NUDJ_DOMAIN = "loyalty.mycompany.com";

// Endpoint that generates the login link
app.get("/nudj-login-link", (req, res) => {
  // Get the authenticated user from your system
  const user = req.user; // Assuming you have authentication middleware

  // Create the token payload
  const tokenPayload = {
    userId: user.id,
    email: user.email,
    locale: user.preferredLanguage || "en",
    username: user.displayName,
  };

  // Sign the token
  const userToken = sign(tokenPayload, NUDJ_CLIENT_SECRET, {
    expiresIn: "1h",
  });

  // Build the Nudj login URL
  const loginUrl = `https://${NUDJ_DOMAIN}/api/link?userToken=${userToken}&clientId=${NUDJ_CLIENT_ID}`;

  // Return the URL to your frontend
  res.json({ loginUrl });
});

app.listen(3000, () => console.log("Server running"));

Code Example: React Frontend

import { useEffect, useState } from "react";

export function NudjLoginButton() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const handleLogin = async () => {
    setLoading(true);
    setError(null);

    try {
      // Call your backend to get the login URL
      const response = await fetch("/nudj-login-link");
      const { loginUrl } = await response.json();

      // Redirect to Nudj
      window.location.href = loginUrl;
    } catch (err) {
      setError("Failed to generate login link");
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={handleLogin} disabled={loading}>
        {loading ? "Connecting..." : "Go to Loyalty Program"}
      </button>
      {error && <p style={{ color: "red" }}>{error}</p>}
    </div>
  );
}

Security Considerations

Protect Your Client Secret

Your clientSecret is sensitive. Only use it on your backend, never in frontend code or client-side JavaScript.

Use HTTPS

Always use HTTPS for token generation and transmission. HTTP will expose tokens.

Token Expiration

Set token expiration to a reasonable value (1 hour is typical). Shorter is more secure; longer is more convenient.

Validate User Input

Sanitize user data before putting it in the token. Never include sensitive information like passwords or API keys.

Troubleshooting

This usually means the token is invalid or the clientId is wrong. Verify:
  • The token was signed with your correct clientSecret
  • The clientId matches your API Configuration
  • The token hasn’t expired
  • The token is being passed in the URL correctly
The token signature is invalid. This means either:
  • You’re using the wrong clientSecret to sign the token
  • The token was tampered with or corrupted
  • You’re using a different algorithm than expected (use HS256, the default for jsonwebtoken)
Verify your clientSecret is correct and hasn’t been rotated.
Some user properties are optional. If you didn’t include email, Nudj generates a placeholder. If you didn’t include username, it defaults to “anonymous”.Include all desired properties in the token payload, and they’ll be stored.
Each userId should map to exactly one email. If you send the same userId with different emails, Nudj updates the user’s email. This might cause issues if you expect a 1:1 mapping.Ensure your userId and email are always consistent for the same user.

Next Steps

  1. Get your API credentials from Nudj API Configuration
  2. Implement token generation in your backend
  3. Build the login URL on your frontend
  4. Test with a real user
  5. Monitor for errors in your logs
Need help? Contact Nudj support.