This guide explains how to authenticate users directly into the Nudj Platform using JWT tokens that encode user metadata. This method is suitable for scenarios where users are already authenticated in your platform and you want to pass them into Nudj seamlessly.
Quick Start ✅
1
Verify Prerequisites
Ensure users are already authenticated in your platform and you want to pass them into Nudj without showing a login screen.
2
Get Credentials
Retrieve your credentials from Developer Settings:
- Client ID
- Client Secret
- API Token (for alternative method)
3
Generate User Token
Generate a signed JWT containing the user’s details (userId, email, locale, etc.) using your clientSecret.
4
Build Auto-Login URL
Create the authentication URL:
5
Redirect User
Share the link with the user or redirect them to it for instant Nudj login.
When to Use This Method
Use This Method
- Users are already authenticated in your platform
- You want seamless session continuation in Nudj
- No login screen should be shown
- Single sign-on (SSO) experience required
Don't Use This Method
- Users arrive directly at Nudj without authentication
- Users need to create new accounts
- OAuth integration is more appropriate
If users arrive directly at Nudj without being authenticated, use OAuth Integration Setup instead.
Detailed Implementation Guide
1. Retrieve Your Credentials
Navigate to Admin Panel → Settings → Organization → Developer Settings tab and copy your:Your unique client identifier
Your secret key for signing tokens (keep this secure!)
API token for alternative authentication method (optional)
2. Generate the User Token
3. Build the Auto-Login URL
You can use either the User Token method (recommended) or the API Token method:- User Token Method (Recommended)
- API Token Method (Alternative)
Security Note: The
callbackPath parameter must be a relative path starting with / and will be validated against an allowlist on the server to prevent open-redirect vulnerabilities. Full URLs or paths missing the leading slash will be rejected.4. User Property Requirements
Unique identifier for the user. This is stored as
externalId in Nudj and used for account identification.User’s email address. Must be unique per user. If omitted, Nudj generates a placeholder email in the format
${userId}@${organisationId}.com and the user can only log in via direct links (no magic link/self-login).Language/region code (e.g.,
en, fr, es). Defaults to en if not provided.Display name shown in Nudj UI. Defaults to “anonymous” until updated by the user.
Special identifier provided by Nudj to merge an anonymous session with the authenticated user account. Used for preserving user progress before authentication. This ID is typically available in the session or URL parameters when anonymous login features are enabled.
Initial points to award the user upon account creation. Only applied for new users, not updates. Creates a points transaction record automatically.
How It Works
Account Creation & Management
- New Users
- Existing Users
- Anonymous Merge
When a user doesn’t exist in Nudj:
- Nudj receives the signed JWT token
- Validates the token signature using your Client Secret
- Creates a new account with provided details
- Awards initial points if specified (creates transaction record)
- Automatically signs the user in
- User lands in Nudj fully authenticated
Example Implementation Flow
1
User Login
User logs into your platform using your existing authentication system.
2
Token Generation
Your backend generates a signed JWT with the user’s information.
3
URL Construction
Your system builds the Nudj authentication URL with the token and client ID.
4
Redirect
User is redirected to the Nudj URL either automatically or via a button/link.
5
Seamless Access
User lands in Nudj fully signed in with no login screen shown.
Environment Configuration
The API Link authentication works across multiple Nudj applications:- Production
- Staging
- Development
The
/api/link endpoint is available in multiple Nudj applications:- user app (port 3000)
- admin app (port 4000)
- creator-frontend app
- api service
Complete Integration Example
Here’s a full example of implementing API Link authentication in an Express.js application:Error Responses
The/api/link endpoint returns specific HTTP status codes for different error conditions:
| Status Code | Error | Description |
|---|---|---|
401 | Unauthorized | Missing or invalid token/credentials |
403 | Forbidden | Valid token but insufficient permissions |
404 | Not Found | Domain or organization not found |
422 | Unprocessable Entity | Invalid user data or parameters |
500 | Internal Server Error | Server-side processing error |
Security Best Practices
Token Security
Token Security
- Generate tokens only on your backend server
- Never expose Client Secret in client-side code
- Use environment variables for sensitive credentials
- Set appropriate token expiration times (1 hour recommended)
- Rotate Client Secrets periodically
- Note: Organizations can have multiple Client Secrets configured
Data Validation
Data Validation
- Validate user data before token generation
- Ensure userId is unique and consistent
- Sanitize email addresses and usernames
- Handle missing optional fields gracefully
- Verify email format if provided
Error Handling
Error Handling
- Implement proper error handling for token generation failures
- Provide fallback authentication methods
- Log authentication attempts for security monitoring
- Handle expired tokens gracefully
- Implement retry logic with exponential backoff
CORS & Security Headers
CORS & Security Headers
- Configure CORS to allow your domains
- Implement CSRF protection for session management
- Use HTTPS for all authentication requests
- Set appropriate security headers
Troubleshooting
Token Generation Fails
Token Generation Fails
Problem: JWT signing throws an errorSolutions:
- Verify Client Secret is correctly set in environment variables
- Check that the jsonwebtoken library is properly installed
- Ensure user data object has all required fields
- Validate that expiration time is properly formatted
User Not Authenticated in Nudj
User Not Authenticated in Nudj
Problem: User is redirected but sees login screenSolutions:
- Verify the token is properly URL-encoded in the link
- Check that clientId matches your Nudj configuration
- Ensure token hasn’t expired (check expiration time)
- Validate domain matches your Nudj instance
User Data Not Updated
User Data Not Updated
Problem: Changes to user properties don’t reflect in NudjSolutions:
- Ensure userId remains consistent (it’s the primary identifier)
- Check that updated fields are included in the token
- Verify token signature is valid
- Clear browser cache and try again
Anonymous Session Not Merged
Anonymous Session Not Merged
Problem: User loses progress after authenticationSolutions:
- Include the anonymousAccountId provided by Nudj
- Ensure the ID is passed correctly in the token
- Check timing - merge must happen during authentication
- Contact Nudj support if issue persists
API Reference
For detailed API documentation and additional authentication methods, see:Authentication Guide
Complete guide to all Nudj authentication methods
OAuth Integration
Set up OAuth providers for direct login
API Configuration
Manage API keys and authentication settings
Integration API Docs
Full Integration API reference
Support
If you encounter any issues or need assistance with implementation:- Technical Support: Contact your Nudj account manager
- Documentation: Visit docs.nudj.cx
- API Status: Check status.nudj.cx
- Community: Join the Nudj Developer Community

