API Link User Token Authentication

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

Get your clientId and clientSecret from Nudj API Configuration
Generate a signed JWT containing user details using your clientSecret
Build the auto-login URL with the token and clientId
Redirect the user to that URL
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

Log into your Nudj admin panel
Navigate to Organisation Settings → API Configuration
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: "user@example.com",     // ⚠️ 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

Property	Required?	Description
`userId`	✅ Yes	Unique identifier for the user. Stored as `externalId` in Nudj.
`email`	⚠️ Optional	User’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`	✅ Yes	Language/region code (e.g., “en”, “fr”, “es”). Defaults to “en” if not provided.
`username`	⚠️ Optional	Display name shown in Nudj UI. Defaults to “anonymous” until updated.
`anonymousAccountId`	⚠️ Optional	Provided 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:

Nudj checks if a user with that userId already exists
If not, creates a new account with the provided details
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:

User logs into your platform

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

Backend generates token

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

Frontend builds the link

Your frontend creates the login URL with the token and clientId

User is redirected

Your frontend redirects the user to the Nudj login URL

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

'Invalid token' error

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.

User created but missing data

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.

Same user landing with different emails

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

Get your API credentials from Nudj API Configuration
Implement token generation in your backend
Build the login URL on your frontend
Test with a real user
Monitor for errors in your logs

Need help? Contact Nudj support.

API Reference

Authentication & User Linking

Webhooks

MCP Server

Resources

Quick Start

When to Use This Method

Retrieve Your Credentials

Generate the User Token

Token Properties

Auto-Sign the User Into Nudj

How It Works

Account Identification

Account Creation

Account Updates

Email Handling

Example Integration Flow

Code Example: Node.js Backend

Code Example: React Frontend

Security Considerations

Protect Your Client Secret

Use HTTPS

Token Expiration

Validate User Input

Troubleshooting

Next Steps

​Quick Start

​When to Use This Method

​Retrieve Your Credentials

​Generate the User Token

​Token Properties

​Auto-Sign the User Into Nudj

​How It Works

​Account Identification

​Account Creation

​Account Updates

​Email Handling

​Example Integration Flow

​Code Example: Node.js Backend

​Code Example: React Frontend

​Security Considerations

Protect Your Client Secret

Use HTTPS

Token Expiration

Validate User Input

​Troubleshooting

​Next Steps

Quick Start

When to Use This Method

Retrieve Your Credentials

Generate the User Token

Token Properties

Auto-Sign the User Into Nudj

How It Works

Account Identification

Account Creation

Account Updates

Email Handling

Example Integration Flow

Code Example: Node.js Backend

Code Example: React Frontend

Security Considerations

Troubleshooting

Next Steps