Skip to content
Nerion
Home

Explore the platform

GamesPlay with friendsCreators

Featured games

Backrooms MODPo-KemonitoBackrooms Found FootageKasuSafio 1All games

For creators

How to publishDashboardMonetizationAPI and webhooksCreator agreement
About us News
ES
ES Download

For developers

API and webhooks

Updated October 12, 2026

Getting started

What you can doNo code: notices in Discord

API

API keysCalling the APIEndpointsErrors

Webhooks

How they workWhat your server receivesVerifying the signatureRetries and automatic shutdown

Events

Event list

Getting started

What you can do

Nerion lets you connect your instance to your own tools: a Discord bot, your website, a panel or your own whitelist system. There are two parts:

  • The API: your code asks Nerion things (who's playing, who has access, what changed) and can give or remove access. It uses API keys.
  • Webhooks: Nerion tells your code (or a Discord channel) whenever something happens: a player joins, someone asks for access, a crash…

Both are set up in the dashboard, in your instance › Config › Developers. You need to be the owner or have the integrations permission to see it.

No code: notices in Discord

If all you want is to see what happens on your instance in a channel of your Discord server, you don't need anything else on this page:

  1. In Discord: Edit channel › Integrations › Webhooks › New webhook › Copy webhook URL.
  2. In the dashboard: Config › Developers › New webhook, pick A Discord channel, paste the URL and tick the events you want.
  3. Press Test: a message should show up in the channel.

Messages come in English or Spanish, as you choose, for example “▶️ Pablo opened the instance” or “💥 Pablo crashed”, with a link that opens that crash in the dashboard.

API

API keys

Create a key in Config › Developers › New key. Give it a name, pick what it can do and, optionally, when it expires. The key (it starts with nrn_) is shown only once: copy it and keep it somewhere safe, like an environment variable. If you lose it, revoke it and make a new one.

PermissionWhat it allows
instance:readSee the instance and its servers.
players:readSee who's playing right now.
allowlist:readSee the allowlist.
allowlist:writeGive and remove access.
activity:readSee the activity log.
  • A key acts with the permissions of whoever created it. If that person loses the integrations permission on the instance, the key stops working. What the key does is logged in the activity under their name.
  • Each instance can have up to 10 active keys. Revoking one cuts its access immediately.
  • Never put a key in code that runs in a browser or in a mod: anyone could read it.

Calling the API

Every route hangs off your instance's URL, shown in Config › Developers:

https://launcherapi.onesimpledev.net/api/v1/instances/{instanceId}

Send the key in the Authorization header of every request:

curl -H "Authorization: Bearer nrn_…" \
  https://launcherapi.onesimpledev.net/api/v1/instances/{instanceId}

Responses are JSON. Each key can make up to 120 requests per minute; past that you get 429 and should wait a little. Fields without a value may be null, and new fields may show up later: ignore the ones you don't know.

Endpoints

Get the instance

GET / · permission instance:read

{
  "id": "6f1c…",
  "name": "Survival Nerion",
  "minecraftVersion": "1.20.1",
  "loader": "FABRIC",
  "loaderVersion": "0.16.5",
  "accessMode": "ALLOWLIST",
  "status": "AVAILABLE",
  "onlinePlayers": 12,
  "onlineServers": 2
}

accessMode: PUBLIC, ACCESS_KEY or ALLOWLIST. status: AVAILABLE, SCHEDULED, MAINTENANCE, DISABLED or ERROR.

List the servers

GET /servers · permission instance:read. The servers registered by the Nerion plugin.

[
  {
    "id": "a41b…",
    "name": "Survival",
    "type": "SURVIVAL",
    "status": "ONLINE",
    "currentPlayers": 8,
    "maxPlayers": 50,
    "lastHeartbeat": "2026-10-12T20:00:00Z"
  }
]

See who's playing

GET /players · permission players:read. Only servers that are online.

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Pablo",
    "avatarUrl": "https://…",
    "serverId": "a41b…",
    "serverName": "Survival"
  }
]

Get the allowlist

GET /allowlist · permission allowlist:read

[
  {
    "accountId": "2c9f…",
    "displayName": "Pablo",
    "source": "MANUAL",
    "addedAt": "2026-10-01T18:30:00Z",
    "expiresAt": null
  }
]

source tells where the access comes from: MANUAL (dashboard or API), or automatic through PATREON, DISCORD, TWITCH or KICK.

Give access

POST /allowlist · permission allowlist:write. Send the Nerion account or a premium Minecraft name:

{ "accountId": "2c9f…" }
{ "minecraftUsername": "Pablo_MC" }

Answers 201:

{ "accountId": "2c9f…", "minecraftUsername": null, "pending": false }

With the Minecraft name of someone who doesn't use Nerion yet, the access is pending ("pending": true) and is given automatically when they sign in to Nerion with that account.

Remove access

DELETE /allowlist/{accountId} · permission allowlist:write. Answers 204.

Get the activity

GET /activity?page=0&size=20 · permission activity:read. Newest first; size goes up to 100.

{
  "items": [
    {
      "id": "e8d2…",
      "action": "INSTANCE_ALLOWLIST_ACCOUNT_ADDED",
      "details": "Added account 2c9f… to the ALLOWLIST",
      "actor": "pablo",
      "createdAt": "2026-10-12T19:58:00Z"
    }
  ],
  "page": 0,
  "size": 20,
  "totalPages": 4,
  "totalItems": 71
}

Errors

Errors come with an HTTP status and, when it applies, a code your code can rely on:

{ "status": 403, "error": "Forbidden", "code": "DEVELOPER_KEY_MISSING_SCOPE", "params": { "scope": "allowlist:write" } }
HTTPcodeWhat happened
401DEVELOPER_KEY_INVALIDThe key is missing, unknown, revoked or expired, or its creator no longer has permission.
403DEVELOPER_KEY_WRONG_INSTANCEThe key belongs to another instance.
403DEVELOPER_KEY_MISSING_SCOPEThe key doesn't have that permission (params.scope).
429DEVELOPER_KEY_RATE_LIMITEDMore than 120 requests in a minute.
400ALLOWLIST_TARGET_REQUIREDaccountId or minecraftUsername is missing.
404ACCOUNT_NOT_FOUNDThere's no such Nerion account.

Webhooks

How they work

A webhook is a URL Nerion sends a POST to whenever one of the events you picked happens. Create them in Config › Developers › New webhook, in one of two formats:

  • A Discord channel: paste a Discord webhook URL and get readable messages. No signature or JSON to handle.
  • Your server (JSON): get the full event as signed JSON. That's the one documented below.

The URL must be https and reachable from the internet (private addresses aren't accepted). Nerion doesn't follow redirects. Each instance can have up to 10 webhooks.

What your server receives

POST /your-path HTTP/1.1
Content-Type: application/json
User-Agent: Nerion-Webhooks/1
X-Nerion-Event: player.joined
X-Nerion-Delivery: 3f0d…
X-Nerion-Timestamp: 1760299200
X-Nerion-Signature: sha256=6a85cb11…

{
  "id": "9b2e…",
  "type": "player.joined",
  "instanceId": "6f1c…",
  "occurredAt": "2026-10-12T20:00:00Z",
  "data": { … }
}
  • id identifies the event. Rarely, an event may arrive twice: if that matters, skip ids you already handled.
  • Events don't always arrive in order; use occurredAt if you need it.
  • Answer with any 2xx status within 10 seconds. If you have slow work to do, answer first and do it afterwards.

Verifying the signature

When you create a JSON webhook you get a secret (it starts with whsec_ and is shown only once; if you lose it, use New secret). Every delivery carries X-Nerion-Signature: sha256=…, a hex HMAC-SHA256 of timestamp + "." + body, where the timestamp is X-Nerion-Timestamp (Unix seconds) and the body is the exact bytes you received. Check it before trusting the event, and reject timestamps older than 5 minutes.

Node.js

import crypto from 'node:crypto';

// rawBody: the body as it arrived (string), before JSON.parse.
function isFromNerion(headers, rawBody, secret) {
  const timestamp = headers['x-nerion-timestamp'];
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`).digest('hex');
  const given = headers['x-nerion-signature'] ?? '';
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return fresh && given.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Python

import hashlib, hmac, time

def is_from_nerion(headers, raw_body: bytes, secret: str) -> bool:
    timestamp = headers.get("X-Nerion-Timestamp", "")
    expected = "sha256=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body,
                                    hashlib.sha256).hexdigest()
    fresh = timestamp.isdigit() and abs(time.time() - int(timestamp)) < 300
    return fresh and hmac.compare_digest(headers.get("X-Nerion-Signature", ""), expected)

Retries and automatic shutdown

  • If your server doesn't answer 2xx (or takes longer than 10 seconds), we retry after 1, 5 and 30 minutes. After that, the delivery is given up.
  • If 10 deliveries in a row are given up, the webhook turns itself off and the dashboard says so. Fix the URL and turn it back on.
  • History shows the latest deliveries with their status, what your server answered and the error. They're kept for 7 days.
  • Test sends a webhook.test event right away and shows what your server answered.

Events

Event list

data only includes the fields that have a value.

player.started_playing · player.stopped_playing

A player opens or closes the instance from the Nerion launcher. No server with the plugin needed.

"data": {
  "playerAccountId": "2c9f…",
  "playerName": "Pablo",            // their Nerion name
  "minecraftUsername": "Pablo_MC",  // the Minecraft account they play with
  "durationSeconds": 1520           // stopped only, when the launcher knows it
}

player.joined · player.left

A player joins or leaves a server running the Nerion plugin. It's detected through the plugin's heartbeat, so it can take a few seconds.

"data": {
  "serverId": "a41b…",
  "serverName": "Survival",
  "player": { "uuid": "069a79f4-…", "name": "Pablo", "avatarUrl": "https://…" }
}

allowlist.added · allowlist.removed

An account gains or loses access to the instance.

"data": { "accountId": "2c9f…", "source": "MANUAL" }

source: MANUAL (dashboard or API), INVITE (an invite by name that came true), or PATREON, DISCORD, TWITCH, KICK (memberships).

access_request.created · access_request.decided

Someone asked for access with /join in your Discord server, and later the staff approved or rejected it.

"data": {
  "requestId": "71ac…",
  "discordUserId": "1234567890",
  "discordUsername": "pablito",
  "playerAccountId": "2c9f…",        // when their Discord is linked to Nerion
  "minecraftUsername": "Pablo_MC",   // when they asked by name
  "status": "APPROVED",              // decided only: APPROVED or REJECTED
  "decidedBy": "moderator"           // decided only
}

crash.reported

A player's game closed with an error, or never started (phase: LAUNCH_FAILED).

"data": {
  "crashId": "c0d3…",
  "phase": "IN_GAME_CRASH",
  "cause": "GPU_DRIVER",
  "exitCode": 1,
  "minecraftVersion": "1.20.1",
  "launcherVersion": "0.1.77",
  "playerAccountId": "2c9f…",
  "playerName": "Pablo",
  "minecraftUsername": "Pablo_MC",
  "dashboardUrl": "https://…/instances?instance=…&section=crashes&crash=c0d3…"
}

cause is the probable cause: GPU_DRIVER, JAVA_TOO_OLD, JAVA_UNAVAILABLE, JAVA_BLOCKED, JAVA_OPTIONS, OUT_OF_MEMORY, JVM_CRASH, DISK_SPACE, LAUNCH_FAILED, GAME_ERROR. dashboardUrl opens that crash in the dashboard (it takes the permission to view reports). Crashes are kept for 30 days.

feedback.created

A player sent a report from the launcher. category: BUG or SUGGESTION.

"data": { "feedbackId": "f33d…", "category": "BUG", "body": "The map won't load…", "playerAccountId": "2c9f…" }

activity.logged

Any change that goes into the instance's activity log. The most complete event, and the one that sends the most.

"data": { "action": "INSTANCE_MOD_ADDED", "actor": "pablo", "details": "sodium-0.5.11.jar" }

webhook.test

Only when you press Test.

"data": { "message": "This is a test event from Nerion." }
Nerion

The platform that connects players with Minecraft experiences.

Nerion

HomeAbout usNews

Platform

GamesPlay with friendsCreators

Legal

TermsPrivacyCreator agreement

Community

Discord

© 2026 Nerion. Nerion is not affiliated with Mojang Studios or Microsoft. Minecraft is a trademark of Mojang Studios.