Skip to main content

​
Overview

The Admin API is your command center for the Nudj platform, providing comprehensive control over every aspect of your gamified community. It enables you to build, customize, and manage engaging experiences at scale.

​
Base URL

https://{subdomain}.nudj.cx/api/v2/admin
Replace {subdomain} with your organization’s subdomain (e.g., acme-corp.nudj.cx).

​
Authentication

Authorization: Bearer YOUR_ADMIN_TOKEN
Admin tokens grant extensive platform control. Only trusted administrators should have access. Tokens are scoped to specific organizations and roles.

​
Core Capabilities

Community Builder

Design branded spaces with custom themes, domains, and content

Gamification Engine

Configure challenges, achievements, leaderboards, and progression systems

Reward Manager

Distribute prizes, manage giveaways, and track redemptions

User Administrator

Manage members, teams, roles, and permissions at scale

Content Controller

Create posts, moderate content, and manage community interactions

Platform Configurator

Set feature flags, integrations, variables, and system settings

​
Platform Management Areas

​
🏗️ Community Building

Build and customize engaging community spaces with full control over branding, structure, and member experience.
Complete community lifecycle management
  • Create multi-tenant branded spaces
  • Configure onboarding flows and requirements
  • Set member permissions and access controls
  • Customize navigation and layout
  • Manage community-wide settings and features
// Create a new community
await admin.communities.create({
  name: "Developer Hub",
  subdomain: "devs",
  theme: { primaryColor: "#7C3AED" },
  features: ["challenges", "rewards", "leaderboards"]
})
Visual customization engine
  • Custom color schemes and typography
  • Logo and asset management
  • Light/dark mode configurations
  • Component styling overrides
  • Custom CSS injection
Key endpoints:
  • GET/PATCH /themes - Theme configuration
  • POST /domains - Custom domain setup
Rapid deployment with pre-built templates
  • Community templates for different industries
  • Challenge bundles for common use cases
  • Achievement sets for various goals
  • Reward catalogs by category
  • Action libraries for engagement
// Deploy from template
await admin.templates.createEntity({
  templateId: "fitness-community",
  customizations: { name: "FitClub 2024" }
})

​
🎮 Gamification System

Design sophisticated engagement mechanics with challenges, achievements, and progression systems.
Multi-step quest builder
  • Sequential and parallel action paths
  • Multiple action types available
  • Prerequisites and unlocking logic
  • Time-based challenges
  • Group challenges for team competition
Action Types Available:
  • Social media integrations
  • Content creation (posts, comments)
  • External link actions
  • Custom actions
// Create multi-action challenge
const challenge = await admin.challenges.create({
  title: "Social Media Master",
  actions: [
    { type: "twitter_follow", target: "@nudj" },
    { type: "instagram_post", hashtag: "#NudjCommunity" },
    { type: "youtube_watch", videoId: "abc123", duration: 300 }
  ],
  rewards: { points: 500, xp: 100 }
})
Milestone and badge configuration
  • Progress-based achievements
  • Hidden/secret achievements
  • Tiered achievement chains
  • Custom unlock criteria
  • Visual badge designer
Criteria Types:
  • Action completions
  • Point thresholds
  • Streak maintenance
  • Community contributions
  • Time-based milestones
Competitive dynamics engine
  • Global, regional, and group leaderboards
  • Multiple ranking metrics (points, XP, achievements)
  • Time-scoped competitions (daily, weekly, seasonal)
  • Prize distribution automation
  • Real-time position tracking
// Configure weekly leaderboard with rewards
await admin.leaderboards.create({
  type: "weekly",
  metric: "points",
  rewards: [
    { rank: 1, prize: "premium_membership" },
    { rank: [2, 5], prize: "bonus_points", amount: 1000 },
    { rank: [6, 10], prize: "badge" }
  ]
})
Advanced gamification mechanics
  • Spin wheels and slot machines
  • Daily check-in bonuses
  • Loot boxes and mystery rewards
  • Mini-games and instant wins
  • Probability-based rewards
Key endpoints:
  • POST /game-configs - Create game
  • PATCH /game-configs/{id} - Update mechanics

​
🎁 Rewards & Incentives

Comprehensive reward management from creation to fulfillment, supporting physical, digital, and experiential prizes.
Multi-type reward system
  • Digital: Codes, vouchers, subscriptions
  • Physical: Merchandise, products, gift cards
  • Experiential: Event tickets, meetups
  • Virtual: Points, badges, titles
Inventory Management:
  • Stock tracking and alerts
  • Automatic reordering
  • Expiration handling
  • Regional availability
Flexible reward allocation
  • Direct: Manual distribution to users
  • Earned: Automatic on achievement
  • Purchased: Points marketplace
  • Giveaway: Random selection
  • Leaderboard: Rank-based distribution
  • Milestone: Progress rewards
// Process giveaway
await admin.rewards.processGiveaway({
  rewardId: "prize_123",
  selectionMethod: "random",
  numberOfWinners: 10,
  eligibilityCriteria: {
    minPoints: 100,
    completedChallenges: ["onboarding"]
  }
})
End-to-end fulfillment
  • Redemption workflows
  • Shipping integration
  • Digital delivery automation
  • Tax documentation support
  • Customer support tools

​
👥 User & Team Management

Complete member lifecycle management with sophisticated role-based access control and team collaboration features.
Comprehensive member management
  • Bulk import/export
  • Custom profile fields
  • Role assignment
  • Activity monitoring
  • Points/XP adjustments
  • Account suspension/deletion
// Bulk user operations
await admin.users.bulkImport({
  users: csvData,
  sendWelcomeEmail: true,
  assignToGroups: ["new_members"],
  initialPoints: 100
})
Multi-level hierarchy
  • Organization structure
  • Department/team creation
  • Role-based permissions
  • Invitation management
  • Access control lists
  • Cross-team competitions
Currency management system
  • Manual point adjustments
  • Transaction history
  • Balance corrections
  • Refunds and reversals
  • Currency conversion
  • Audit trails

​
⚙️ Platform Configuration

System-wide settings and integrations for complete platform customization.
Identity provider configuration
  • SSO/SAML setup
  • OAuth providers
  • Magic link authentication
  • MFA requirements
  • Session management
  • Password policies
Third-party connections
  • Social media platforms
  • Analytics services
  • Communication tools
  • Custom webhook integrations
// Configure integration
await admin.thirdPartyConfig.update({
  twitter: {
    apiKey: process.env.TWITTER_KEY,
    apiSecret: process.env.TWITTER_SECRET,
    webhookUrl: "https://api.nudj.cx/webhooks/twitter"
  }
})
Dynamic configuration
  • Environment-specific settings
  • A/B testing parameters
  • Feature toggles
  • Rate limits
  • Threshold values
  • System constants
Real-time event streaming
  • Custom event subscriptions
  • Payload customization
  • Retry policies
  • Event filtering
  • Webhook security
  • Audit logging

​
API Resource Groups

  • Core Resources
  • Gamification
  • Configuration
  • Templates
ResourceOperationsPurpose
CommunitiesCRUDCommunity spaces management
UsersCRUD + BulkMember administration
ChallengesCRUD + DistributionQuest configuration
ActionsCRUD + ReorderActivity building blocks
AchievementsCRUD + DistributionMilestone system
RewardsCRUD + GiveawayPrize management
PostsCRUDContent management
TeamsCRD + InviteOrganization structure

​
Quick Start Examples

import { createAdminClient } from '@nudj-digital/api/admin';

const admin = createAdminClient({
  baseUrl: 'https://acme-corp.nudj.cx/api/v2/admin',
  headers: {
    'Authorization': `Bearer ${process.env.NUDJ_ADMIN_TOKEN}`
  }
});

// Create complete challenge with rewards
const challenge = await admin.challenges.create({
  title: "Welcome Week Challenge",
  description: "Complete these actions to earn rewards!",
  startDate: new Date(),
  endDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
  actions: [
    { type: "profile_complete", points: 50 },
    { type: "first_post", points: 100 },
    { type: "invite_friend", points: 150 }
  ],
  rewards: {
    completion: { points: 500, badge: "early_adopter" },
    leaderboard: [
      { position: 1, reward: "premium_month" },
      { position: [2, 10], reward: "bonus_points", amount: 1000 }
    ]
  }
});

// Process reward giveaway
const winners = await admin.rewards.processGiveaway({
  rewardId: "reward_abc123",
  numberOfWinners: 5,
  eligibility: {
    minEngagementScore: 80,
    requiredChallenges: ["onboarding"]
  }
});

​
Common Workflows

  1. Create campaign structure with challenges
  2. Configure rewards and distribution rules
  3. Set up leaderboards and competitions
  4. Enable relevant feature flags
  5. Configure webhooks for tracking
  6. Import or invite users
  7. Monitor via analytics
  1. Create reward with inventory
  2. Define eligibility criteria
  3. Set participation period
  4. Process random selection
  5. Notify winners
  6. Handle fulfillment
  7. Generate tax documents
  1. Create organization and community
  2. Configure SSO authentication
  3. Apply custom theme and domain
  4. Set up team structure
  5. Import users with roles
  6. Deploy from templates
  7. Configure integrations
  1. Create time-limited challenges
  2. Configure special rewards
  3. Set up event leaderboards
  4. Enable event features
  5. Schedule content
  6. Automate distributions
  7. Archive post-event

​
Response Format

All Admin API responses follow a consistent structure: 
{
  "data": {
    "id": "resource_123",
    "type": "challenge",
    "attributes": {
      "title": "Welcome Challenge",
      "status": "active",
      "startDate": "2024-01-15T00:00:00Z"
    },
    "relationships": {
      "actions": {
        "data": [
          { "id": "action_456", "type": "action" }
        ]
      }
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_abc123",
    "version": "2.0"
  }
}

​
Error Handling

  • Error Codes
  • Error Response
  • Best Practices
CodeDescriptionResolution
INSUFFICIENT_PERMISSIONSMissing required roleCheck admin permissions
RESOURCE_LOCKEDConcurrent modificationRetry with backoff
VALIDATION_ERRORInvalid input dataCheck request schema
DEPENDENCY_ERRORRelated resource issueResolve dependencies
QUOTA_EXCEEDEDLimit reachedUpgrade plan or wait
INTEGRITY_ERRORData consistency issueContact support

​
Rate Limits & Performance

Admin operations can affect many users. Rate limits are enforced to maintain platform stability.
  • Rate Limits
  • Optimization Tips
Rate limits are enforced on all Admin API endpoints. Check response headers for current limits:
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
  • Retry-After

​
Security & Compliance

  • Access Control
  • Audit Logging
  • Data Protection
Role-Based Permissions
RoleCapabilities
super_adminFull platform control
adminCommunity management
moderatorContent and users
analystRead-only access
supportUser assistance
Security Requirements
  • Strong authentication required for admin accounts
  • API tokens should be kept secure and rotated regularly

​
Migration & Deployment

// Export from staging
const config = await staging.admin.export({
  include: ['challenges', 'rewards', 'achievements'],
  excludePII: true
});

// Import to production
await production.admin.import({
  data: config,
  mode: 'merge', // or 'replace'
  dryRun: true   // Test first
});

​
Advanced Features

Bulk Operations

Process multiple records efficiently with batch endpoints

Webhook Support

Real-time event notifications for system changes

​
Support & Resources

API Reference

Detailed endpoint documentation

SDKs & Libraries

Official client libraries

Status Page

Service health monitoring

Developer Forum

Community support

Enterprise Support

Priority assistance

Changelog

Latest updates
⌘I