Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt

Use this file to discover all available pages before exploring further.

The Nudj Platform APIs support two authentication header schemes. Both are verified by the same tRPC auth middleware (apps/api/trpc/init.ts) and both work on every endpoint — pick whichever suits your client.
  1. Authorization: Bearer <token> — the modern, revocable, RBAC-scoped path. Recommended for new integrations.
  2. x-api-token: <token> — the legacy alias. Still fully supported.
The middleware strips an optional Bearer prefix from either header before verifying the signature, so the two paths are equivalent at the signature layer.

Authorization: Bearer

Recommended for new integrationsRBAC-scoped, per-token revocation. Jump to Authorization: Bearer.

x-api-token

Legacy aliasLong-lived JWT. Jump to x-api-token.

​
Authorization: Bearer

Bearer tokens are the modern auth path introduced across NUDJ-4411 / NUDJ-4819 / NUDJ-5354. They carry a type claim, support per-community RBAC scoping, and are verified against a revocation cache on every request — revoking one takes effect within seconds.

​
Get a Bearer token

1

Open Developer Settings

Go to Settings → Organisation → Developer.
2

Generate a token

Click Generate New Token. Pick a role (Viewer / Moderator / Manager / Admin / SuperAdmin) and optionally scope it to a specific community.
3

Copy it immediately

Tokens are shown once. Store in a secrets manager or env var — never commit.

​
Use in requests

Authorization: Bearer YOUR_API_TOKEN
The header is case-insensitive. Tokens are tied to the subdomain they were issued for — replaying a token against a different organisation’s subdomain is rejected.

​
Per-API support

APIAuthorization: Bearerx-api-tokenDeclared in OpenAPI spec
Integration✅✅Both
Admin✅✅Both
Analytics✅✅ (runtime)Bearer only
The Analytics OpenAPI spec currently declares only the Bearer scheme under securitySchemes. The runtime still accepts x-api-token, but the Analytics playground UI surfaces only the Bearer input.

​
x-api-token

​
Get a token

Use the same Developer Settings page as above. Legacy tokens have no type claim and cannot be revoked individually — they remain valid until their expiry.

​
Use in requests

x-api-token: YOUR_API_TOKEN
The header is case-insensitive. An optional Bearer prefix on the value is accepted: 
x-api-token: Bearer YOUR_API_TOKEN

​
Revoke a Bearer token

Bearer tokens can be revoked individually via the Admin API: 
curl -X POST "https://{subdomain}.nudj.cx/api/v2/admin/auth-config/tokens/{tokenId}/revoke" \
  -H "Authorization: Bearer YOUR_ACTIVE_TOKEN"

​
API base URLs

Each organisation has its own subdomain: 
https://{your-subdomain}.nudj.cx/api/v2/{api-type}
Where {api-type} is one of admin, integration, or analytics.
OrganisationSubdomainAdmin API URL
Developmentnudjdevhttps://nudjdev.nudj.cx/api/v2/admin
Stagingnudjstaginghttps://nudjstaging.nudj.cx/api/v2/admin
Your Orgyourcompanyhttps://yourcompany.nudj.cx/api/v2/admin
See Organisation Domains for white-label custom domains managed via the Admin API /domains endpoints.

​
Testing authentication

curl -X GET "https://your-subdomain.nudj.cx/api/v2/admin/communities?limit=10" \
  -H "Authorization: Bearer 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
  • Token issued for a different organisation than the subdomain being requested
  • Incorrect header format

​
403 Forbidden

{
  "message": "Insufficient permissions for this operation.",
  "code": "FORBIDDEN",
  "data": { "httpStatus": 403, "path": "endpoint-name" }
}
Common causes:
  • Token lacks the required RBAC role
  • Token scoped to a different community than the one the endpoint targets
  • Endpoint requires a higher tier (admin vs moderator vs viewer)
See Errors for the full list of error shapes across every status code.

​
Other headers you may need

HeaderPurposeSee
x-languageRequest translated response bodies in a specific localeInternationalization
x-user-access-tokenUser-level auth on embed/widget flowsAPI link user authentication
x-admin-user-access-tokenPer-user RBAC when proxying through the admin appOAuth/SSO integration

​
Security best practices

Never expose API tokens in client-side JavaScript, public repositories, URL parameters, or browser storage.
  1. Store in secret managers — use env vars or a secret store, never source control.
  2. Rotate regularly — especially when team members change.
  3. Scope minimally — use the least-privilege RBAC role the token actually needs.
  4. Revoke compromised Bearer tokens — don’t wait for them to expire.
  5. Use server-side requests only — the APIs are not CORS-enabled for browser origins.

​
Troubleshooting

  • Verify no extra whitespace or line breaks.
  • Confirm the token hasn’t been revoked.
  • Ensure you’re hitting the correct subdomain — tokens are org-scoped.
  • Verify the full path including /api/v2/.
  • Check the API type (admin vs integration vs analytics).
  • Confirm the endpoint exists in the API reference.
  • API runs on https://localhost:3000 with a self-signed cert — use --insecure or NODE_TLS_REJECT_UNAUTHORIZED=0.
  • Confirm MongoDB is running and the org exists in the dev database.

​
Need user-linked authentication?

OAuth Integration

Configure OIDC so users can sign in via your existing auth provider.

API Link User Token

Auto-sign authenticated users into Nudj using JWT tokens.

Developer Settings

Access your API credentials and configuration.