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)
Never expose your Client Secret in client-side code or public repositories. Always generate tokens on your backend server.
Note: Nudj stores organization-level credentials. In your application, load secrets securely (e.g., environment variables or a secret manager), never from client code.
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)
Critical Security Warning: Never put JWTs or API tokens in frontend redirects using
window.location.href
as this exposes sensitive credentials in browser history, logs, and referrer headers. Always use server-side redirects (res.redirect()
) to transmit signed tokens. If client-side navigation is absolutely required, implement a secure token exchange flow using short-lived authorization codes instead of exposing JWTs directly.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
Always follow these security guidelines when implementing API Link authentication:
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