NoxAeApi

Getting Started

Quickstart

Get NoxAeApi running on your Minecraft server and make your first request in a few minutes.

Install the plugin

NoxAeApi is a standard server plugin. Download the latest NoxAeApi.jar, place it in your server's plugins/ directory, and restart to generate the default configuration.

Installation
# 1. Download NoxAeApi.jar
# 2. Drop it into your server's plugins/ folder
server/
└── plugins/
    └── NoxAeApi.jar

# 3. Restart the server to generate the config
NoxAeApi requires Java 17+ and a compatible Minecraft server.
View Full Plugin Setup & Configuration Guide (Paper, Fabric, Velocity)

Configure License & API Keys

Open plugins/NoxAeApi/config.yml. You MUST obtain an NxGate license key from your dashboard and insert it into license-key under keys. Additionally, configure your API keys with optional read-only scopes or endpoint allowlists.

config.yml
# plugins/NoxAeApi/config.yml
# ── NxGate License ───────────────────────────────────────────────────────────
# Obtain your license key from the NxGate dashboard. The plugin requires a valid key to run.
license-key: 'REPLACE_WITH_YOUR_NXGATE_LICENSE_KEY'

# ── API Server Configuration ────────────────────────────────────────────────
server:
  port: 8080
  
  # Optional: Multi-key authentication system
  # Supports read-only scopes and endpoint-specific allowlists.
  keys:
    primary-admin:
      key: "REPLACE_WITH_A_LONG_RANDOM_STRING"
      read-only: false
    dashboard-viewer:
      key: "ANOTHER_RANDOM_STRING_HERE"
      read-only: true
      allowed-endpoints:
        - "/v1/players"
        - "/v1/server/health"

# ── Rate Limiting & Security ────────────────────────────────────────────────
security:
  # Limit requests per minute (per IP or key)
  rate-limit:
    enabled: true
    requests-per-minute: 120
    
  # Restrict API access to specific IPs (e.g., your web dashboard server)
  ip-whitelist:
    enabled: false
    allowed:
      - "203.0.113.10"
      - "192.168.1.100"
      
  # Log sensitive actions to a file (e.g. kicking players, exec console)
  audit-log:
    enabled: true

# ── Realtime & Hooks ────────────────────────────────────────────────────────
# Broadcast game events to external services
webhooks:
  enabled: false
  urls:
    - "https://your-dashboard.com/api/webhooks/noxae"
  events:
    - "player_join"
    - "player_quit"

# Send alerts to Discord channels
discord:
  enabled: false
  webhook-url: "https://discord.com/api/webhooks/..."
  notify-on:
    - "unauthorized-access"
    - "exec-command"
    - "op-change"

# Enable WebSocket real-time event streaming (/v1/ws/events)
websocket:
  events:
    enabled: true

# ── Network Aggregator (Proxy Mode) ─────────────────────────────────────────
# Enable this ONLY on Velocity/BungeeCord to aggregate backend node data.
network:
  enabled: false
  timeout: 3000
  servers:
    - name: "survival"
      url: "http://10.0.0.1:8080"
      key: "survival-secret-key"
    - name: "creative"
      url: "http://10.0.0.2:8080"
      key: "creative-secret-key"

Advanced Configuration Features

  • NxGate License Key: Mandatory for the plugin to start. Obtain this from the NxGate Dashboard.
  • Multi-Key System: Support for multiple API keys with fine-grained access (read-only scopes or specific endpoints like allowed-endpoints).
  • Rate Limiting & Security: Enforce requests-per-minute per IP/key, restrict access via ip-whitelist, and enable audit-log for sensitive actions.
  • Webhooks & Discord: Push real-time game events to HTTP webhooks or send critical alerts (e.g., unauthorized access) to a Discord channel.
  • Network Aggregator: Enable proxy mode on BungeeCord or Velocity to aggregate backend nodes and query the entire network via /v1/network/*.

Keep your key secret

The API key grants full control of your server. Never commit it to source control or ship it in client-side code. See Authentication

Your first request

With the server running, confirm connectivity with the health check. Every endpoint is versioned under /v1.

GET /v1/ping
curl https://mc.example.com/v1/ping \
  -H "key: YOUR_API_KEY"

A healthy server responds with:

Response
"pong!"

Now try reading live server info:

GET /v1/server
curl https://mc.example.com/v1/server \
  -H "key: YOUR_API_KEY"

Frequently Asked Questions

Find solutions to common network issues, connection refused errors, firewall rules, and permission setup.

This error indicates your client could not establish a TCP handshake with the specified IP and port.

Troubleshooting steps:

  1. Server logs: Check console logs for [NoxAeApi] HTTP server listening on port 8080.
  2. Host Binding: Set server.host: "0.0.0.0" in plugins/NoxAeApi/config.yml.
  3. Java Runtime: Ensure Java 17 or Java 21+ (java -version).
Terminal
# Test connectivity locally from the server console
curl -I http://127.0.0.1:8080/v1/ping

Next steps

You're connected. From here you can explore the rest of the API.

AuthenticationExamplesAPI Reference