HytaleBanList is moving to a completely free-to-use on all tiers model, you can support us on Ko-Fi!
Hytale Ban List
Menu
Plugin Developer Guide

Building a plugin integration?

API IntegrationDependency (HBLCore Events)

If you're a plugin developer shipping an integration that server owners install and configure with their own Hytale Ban List API key, the provider field lets you tag every request with your plugin's identity — so your usage is tracked separately from the server's own calls.

Recommended

Zero-config setup

Instead of asking server owners to manually paste an API key into a config file, you can implement a magic link flow so they authenticate straight from the game with a single command and store it for them.

1

Plugin calls the magic link endpoint

In the case where a user wants to activate HBL checks without a key configured, your plugin calls POST /v1/auth/magic (no auth required). Pass your provider name in the body and it will be embedded in the returned URL automatically.
2

Server owner clicks the link

Display the URL in chat. The server owner opens it in their browser, enters their server name, and clicks Activate. Your provider is forwarded silently — the owner doesn't need to do anything extra. The link expires after 15 minutes.
3

Plugin polls and receives the API key and provider

Your plugin polls GET /v1/auth/magic/:token/poll every few seconds. Once activated, the response contains the API key and your provider name. Save both to your config — the key is returned exactly once.
POST /v1/auth/magic — request a magic link
// Pass your provider name to embed it in the activation URL
curl -X POST https://api.hytalebanlist.org/v1/auth/magic \
  -H "Content-Type: application/json" \
  -d '{ "provider": "MyPlugin" }'

// Response — provider is embedded in the magicUrl:
{
  "data": {
    "token": "clxyz...",
    "magicUrl": "https://hytalebanlist.org/activate?token=clxyz...&provider=MyPlugin",
    "expiresAt": "2026-03-09T12:15:00.000Z"
  }
}

// provider is optional — omit the body entirely for a plain link:
curl -X POST https://api.hytalebanlist.org/v1/auth/magic
GET /v1/auth/magic/:token/poll — poll until done
curl https://api.hytalebanlist.org/v1/auth/magic/clxyz.../poll

// While waiting:
{ "data": { "status": "pending" } }

// Once the server owner activates — key (and provider if set) returned exactly once:
{ "data": { "status": "completed", "apiKey": "a3f8c2...", "provider": "MyPlugin" } }

// After retrieval or expiry:
{ "data": { "status": "retrieved" } }
{ "data": { "status": "expired" } }

The endpoint is limited to 3 requests per IP per 24 hours to prevent abuse. Poll every 3–5 seconds and stop after 5 minutes if the server owner hasn't activated.

Manual setup (alternative)

If you prefer, server owners can register their own API key at hytalebanlist.org and add it to a config.json file in your plugin's directory. Your plugin reads the key at startup and includes it in the X-Api-Key header on every request.

What is the provider field?

It's an optional string you include in your API request bodies to identify your plugin. For example, if you ship a plugin called MyPlugin, you include "provider": "MyPlugin" in every request your plugin makes. The platform records it alongside each check, ban, and unban — server owners never need to configure it and existing requests without the field are completely unaffected.

How to use it

1

Choose a consistent identifier

Pick a short, stable name for your plugin — e.g. MyPlugin or ServerGuard. Use the same value across all three endpoints. Max 64 characters.
2

Add it to your request bodies

Include "provider": "YourPluginName" as a field in the JSON body of any plugin API call. It is optional everywhere — leaving it out never causes errors.
3

That's it

Your usage will appear grouped under your provider name in analytics. If you want access to your own usage statistics, contact us to have a developer account enabled — see below.

Examples

Check player on join

POST /v1/plugin/check
curl -X POST https://api.hytalebanlist.org/v1/plugin/check \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: SERVER_OWNERS_API_KEY" \
  -d '{
    "username": "Steve",
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "provider": "MyPlugin"
  }'

Submit a ban

Recommended reasons:

HackingCheatingExploitingGriefingHarassmentToxic BehaviorHate SpeechNSFW ContentSpamBan EvasionScammingInappropriate UsernameAdvertisingOther
POST /v1/plugin/bans
curl -X POST https://api.hytalebanlist.org/v1/plugin/bans \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: SERVER_OWNERS_API_KEY" \
  -d '{
    "username": "Griefer99",
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "reason": "Hacking - speed exploit detected",
    "submittedBy": "ModeratorName",
    "provider": "MyPlugin"
  }'

Revoke a ban

DELETE /v1/plugin/bans/:id
curl -X DELETE https://api.hytalebanlist.org/v1/plugin/bans/ban_xyz789 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: SERVER_OWNERS_API_KEY" \
  -d '{
    "provider": "MyPlugin"
  }'

Developer accounts

View your usage statistics

Plugin developers can request a developer account to unlock access to aggregate usage analytics for their provider name — total checks, bans, and unbans across all server installations, with daily breakdowns and date filtering.

Once enabled, you can lock in a permanent provider name from your Account → Developer tab, and access your analytics from the Developer section of the dashboard.

To request access, contact support with your account username and the provider name you intend to use.

← Back to API Docs