Skip to main content
The Nudj Platform APIs use token-based authentication. You’ll need an API token from your Developer Settings to make API requests.

API Token Authentication

For developers and integrationsStandard JWT tokens from your Developer Settings for server-side API access (covered in this guide)

Enterprise Authentication

For enterprise deploymentsOAuth/SSO integration and user token authentication for seamless user experiences
1

Get Your API Token

Navigate to Settings → Organisation → Developer in your admin dashboard
2

Copy Your Token

Find the API Token field and copy the JWT token value
3

Use in Requests

Include the token in your API requests using the x-api-token header

​
Authentication Headers

All APIs use the same authentication header format: 
# Uses x-api-token header
x-api-token: YOUR_API_TOKEN

# Uppercase variant also works
X-API-TOKEN: YOUR_API_TOKEN

# Bearer prefix is optional
x-api-token: Bearer YOUR_API_TOKEN
Important: All APIs use the same authentication header:
  • Integration API, Admin API & Analytics API: All use x-api-token header
  • Headers are case-insensitive (x-api-token, X-API-TOKEN both work)
  • Bearer prefix is optional for x-api-token headers

​
API Base URLs

The Nudj Platform uses organization-specific subdomains: 
https://{your-subdomain}.nudj.cx/api/v2/{api-type}
Where:
  • {your-subdomain} - Your organization’s unique subdomain
  • {api-type} - Either admin, integration, or analytics
OrganizationSubdomainAdmin API URL
Developmentnudjdevhttps://nudjdev.nudj.cx/api/v2/admin
Stagingnudjstaginghttps://nudjstaging.nudj.cx/api/v2/admin
Your Orgyourcompanyhttps://yourcompany.nudj.cx/api/v2/admin

​
Testing Authentication

API Playground

Use the interactive documentation to test endpoints with your token and subdomain

cURL Examples

Copy and modify the cURL examples with your credentials for quick testing
# Get list of communities
curl -X GET "https://your-subdomain.nudj.cx/api/v2/admin/communities?limit=10" \
  -H "x-api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

​
Error Responses

​
401 Unauthorized

{
  "message": "You must be logged in to access this endpoint.",
  "code": "UNAUTHORIZED",
  "data": {
    "httpStatus": 401,
    "path": "endpoint-name"
  }
}
Common causes:
  • Missing or invalid token
  • Expired token
  • Wrong organization context
  • Incorrect header format

​
403 Forbidden

{
  "message": "Insufficient permissions",
  "code": "FORBIDDEN"
}
Common causes:
  • Token lacks required role
  • Endpoint requires admin permissions

​
Security Best Practices

Never expose API tokens in:
  • Client-side JavaScript
  • Public repositories
  • URL parameters
  • Browser storage
Recommendations:
  1. Store securely - Use environment variables or secret management systems
  2. Rotate regularly - Generate new tokens periodically
  3. Limit scope - Use role-based access control
  4. Monitor usage - Track API calls in your dashboard
  5. Revoke compromised tokens - Immediately invalidate exposed tokens

​
Rate Limiting

API endpoints implement rate limiting:
API TypeLimitWindow
Integration1000 req/minPer organization
Admin500 req/minPer organization
Analytics100 req/minPer organization
Rate limit information is included in response headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​
Troubleshooting

  • Verify no extra spaces or line breaks in token
  • Check you’re using the correct environment URL
  • Ensure token hasn’t expired
  • Confirm organization ID matches
  • Verify the complete API path including /api/v2/
  • Check you’re using the correct API type (admin/integration/analytics)
  • Ensure the endpoint exists in the API reference
  • Ensure API server is running on port 3000
  • Check MongoDB connection in .env.local
  • Verify organization fallback is configured
  • Use —insecure flag for self-signed certificates

​
Need Different Authentication?

OAuth/SSO Integration

For enterprise customersSet up OAuth 2.0 or OpenID Connect for user authentication and SSO

User Token Authentication

For seamless user flowsDirect user authentication with encoded JWT tokens for pre-authenticated scenarios

Developer Settings

Access your API credentials and configuration
⌘I