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
clientIdandclientSecretfrom 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
Retrieve Your Credentials
- Log into your Nudj admin panel
- Navigate to Organisation Settings → API Configuration
- Copy these values:
- Client ID
- Client Secret
Generate the User Token
The user token is a JWT (JSON Web Token) signed with yourclientSecret. It must contain these properties:
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 theuserToken, build the login URL:
How It Works
Account Identification
Each user is identified by theiruserId. 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 anAPI Link token:
- Nudj checks if a user with that
userIdalready 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
emailis provided: Nudj uses it to identify and email the user - If
emailis 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
clientSecret3
Frontend builds the link
Your frontend creates the login URL with the token and
clientId4
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
Code Example: React Frontend
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
User lands on a login page instead of being signed in
User lands on a login page instead of being signed in
This usually means the token is invalid or the
clientId is wrong. Verify:- The token was signed with your correct
clientSecret - The
clientIdmatches your API Configuration - The token hasn’t expired
- The token is being passed in the URL correctly
'Invalid token' error
'Invalid token' error
The token signature is invalid. This means either:
- You’re using the wrong
clientSecretto sign the token - The token was tampered with or corrupted
- You’re using a different algorithm than expected (use
HS256, the default forjsonwebtoken)
clientSecret is correct and hasn’t been rotated.User created but missing data
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
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

