RankDelivery — Minecraft Rank Delivery Plugin

Everything Included

Production-ready, secure, and built for scale. No bloat, no fuss.

Embedded HTTP Server

Zero external dependencies. Self-contained server runs on any port you choose. No Tomcat or Jetty needed.

HMAC + Bearer Auth

SHA-256 HMAC signature verification with Bearer token authentication on every delivery request.

Replay Protection

Configurable timestamp window prevents replay attacks. Old or future-dated requests are rejected.

Rate Limiting

Per-IP rate limiting with configurable thresholds protects your server from abuse and spam.

Duplicate Detection

Every delivery_id is tracked. Duplicate requests are automatically rejected with a clear error.

Placeholder Engine

{player}, {uuid}, {group}, {duration}, {unit}, {product}, {price}, {currency} — all replaced before execution.

Duration & Lifetime Ranks

Temporary ranks with m/h/d/w/mo/y and permanent ranks. Just omit duration or set permanent: true.

Any Console Command

Works with LuckPerms, EssentialsX, CMI, or any plugin. No special integration APIs required.

IP Whitelist

Restrict API access to specific IPs or use wildcards. Production-ready access control.

Setup in 5 Minutes

From zero to delivering ranks. Follow these steps.

Download

Place the Plugin

Drop RankDelivery-1.0.0.jar into your server's plugins/ folder and restart.

Security

Set Your Secret Key

Open plugins/RankDelivery/config.yml and change the default secret key.

yaml# CHANGE THIS — used for Bearer auth + HMAC
secret-key: wJ5rX8pZ2kL9mN4qV7bA1cF3gH6jY0sD

Configure

Port, IP & Whitelist

Defaults work out of the box. For production, lock down allowed-ip.

yamlhost: 0.0.0.0
port: 8080
allowed-ip:
  - "203.0.113.42"
  - "198.51.100.7"

Reload

Apply Changes

Run /rankdelivery reload or restart the server. The plugin logs its startup to console.

Health Check

Verify It's Running

Hit the health endpoint to confirm the server is listening.

bashcurl http://YOUR_SERVER_IP:8080/api/v1/health

# Response:
{"success": true, "plugin": "RankDelivery", "version": "1.0.0", "status": "online"}

Deliver!

Send Your First Rank

Your web store sends a POST to the delivery endpoint. The plugin executes the commands.

bashcurl -X POST http://YOUR_SERVER_IP:8080/api/v1/delivery \
  -H "Authorization: Bearer wJ5rX8pZ2kL9mN4qV7bA1cF3gH6jY0sD" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "order_delivered",
  "delivery_id": "del_001",
  "player": { "username": "Steve123" },
  "product": { "id": "vip_rank", "name": "VIP", "price": 4.99 },
  "rank": { "group": "vip", "duration": { "value": 30, "unit": "days" } },
  "commands": [
    "lp user {player} parent addtemp {group} {duration}{unit}",
    "broadcast &a{player} purchased {product}!"
  ]
}'

API Reference

Three endpoints. One integration. Infinite possibilities.

GET /api/v1/health Server status & plugin info

No authentication required. Use it for monitoring and load balancer health checks.

json — response{
  "success": true,
  "plugin": "RankDelivery",
  "version": "1.0.0",
  "minecraft": "1.21.3",
  "status": "online"
}

POST /api/v1/verify Verify token & connection

Used by web stores to confirm the server is reachable and the configured token is valid.

json — request{
  "token": "wJ5rX8pZ2kL9mN4qV7bA1cF3gH6jY0sD"
}

json — response{
  "success": true,
  "server_id": "srv_001",
  "plugin": "RankDelivery",
  "version": "1.0.0"
}

POST /api/v1/delivery Execute rank delivery commands

Headers: Authorization: Bearer SECRET_KEY · Content-Type: application/json · X-Signature: HMAC-SHA256 (optional)

json — request{
  "event": "order_delivered",
  "delivery_id": "del_98421",
  "timestamp": 1719999999,
  "player": {
    "username": "Steve123",
    "uuid": "8667ba71-b85a-4004-af54-457a9734eed7"
  },
  "product": {
    "id": "vip_rank",
    "name": "VIP",
    "price": 4.99,
    "currency": "USD"
  },
  "rank": {
    "group": "vip",
    "duration": { "value": 30, "unit": "days" }
  },
  "commands": [
    "lp user {player} parent addtemp {group} {duration}{unit}",
    "broadcast &a{player} purchased {product}!"
  ]
}

json — success{
  "success": true,
  "delivery_id": "del_98421",
  "executed": 2,
  "failed": 0,
  "message": "Commands executed successfully."
}

json — error{
  "success": false,
  "error": "Invalid Signature"
}

Permanent (Lifetime) Ranks

Omit duration and set "permanent": true to grant ranks without expiry.

json{
  "rank": { "group": "vip", "permanent": true },
  "commands": ["lp user {player} parent add {group}"]
}

Placeholder Reference

Every placeholder is replaced before commands are sent to the console.

Available Placeholders

{player}player.username → Steve123

{uuid}player.uuid → 8667ba71...

{group}rank.group → vip

{duration}duration.value → 30

{unit}duration.unit (abbr) → d

{product}product.name → VIP

{product_id}product.id → vip_rank

{price}product.price → 4.99

{currency}product.currency → USD

Duration Abbreviations

Unit	Abbr	Example
minutes	m	30m
hours	h	12h
days	d	30d
weeks	w	2w
months	mo	3mo
years	y	1y

Template:

lp user {player} parent addtemp {group} {duration}{unit}

→ lp user Steve123 parent addtemp vip 30d

Command Examples by Plugin

Plugin	Command Template
LuckPerms (temp)	lp user {player} parent addtemp {group} {duration}{unit}
LuckPerms (perm)	lp user {player} parent add {group}
EssentialsX	pex user {player} group add {group}
CMI	cmi usergroup addplayer {player} {group}
Broadcast	broadcast &6{player} &ais now &e{group}&a!

Store Integrations

Works with any backend. Pick your language and copy the snippet.

javascript// RankDelivery — Node.js Integration
const SECRET = 'wJ5rX8pZ2kL9mN4qV7bA1cF3gH6jY0sD';
const SERVER = 'http://YOUR_SERVER_IP:8080';

async function deliverRank({ ign, uuid, productId, productName, price, group, duration, unit }) {
  const body = {
    event: 'order_delivered',
    delivery_id: `del_${Date.now()}`,
    timestamp: Math.floor(Date.now() / 1000),
    player: { username: ign, uuid },
    product: { id: productId, name: productName, price, currency: 'USD' },
    rank: {
      group,
      duration: duration ? { value: duration, unit } : undefined,
      permanent: !duration
    },
    commands: duration
      ? [`lp user {player} parent addtemp {group} {duration}{unit}`]
      : [`lp user {player} parent add {group}`]
  };

  const res = await fetch(`${SERVER}/api/v1/delivery`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${SECRET}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  return res.json();
}

// Example
deliverRank({
  ign: 'Steve123', uuid: '8667ba71...',
  productId: 'vip_rank', productName: 'VIP', price: 4.99,
  group: 'vip', duration: 30, unit: 'days'
}).then(console.log);

php// RankDelivery — PHP Integration
<?php

function deliverRank($ign, $uuid, $productId, $productName, $price, $group, $duration = null, $unit = 'days') {
    $secret = 'wJ5rX8pZ2kL9mN4qV7bA1cF3gH6jY0sD';
    $server = 'http://YOUR_SERVER_IP:8080';

    $payload = [
        'event'       => 'order_delivered',
        'delivery_id' => 'del_' . uniqid(),
        'timestamp'   => time(),
        'player'      => ['username' => $ign, 'uuid' => $uuid],
        'product'     => ['id' => $productId, 'name' => $productName, 'price' => $price],
        'rank'        => $duration
            ? ['group' => $group, 'duration' => ['value' => $duration, 'unit' => $unit]]
            : ['group' => $group, 'permanent' => true],
        'commands'    => $duration
            ? ["lp user {player} parent addtemp {group} {duration}{unit}"]
            : ["lp user {player} parent add {group}"]
    ];

    $ch = curl_init("$server/api/v1/delivery");
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => ["Authorization: Bearer $secret", 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS     => json_encode($payload),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10
    ]);
    $res = curl_exec($ch);
    curl_close($ch);
    return json_decode($res, true);
}

// Example
$result = deliverRank('Steve123', '8667ba71...', 'vip_rank', 'VIP', 4.99, 'vip', 30, 'days');
print_r($result);

python# RankDelivery — Python Integration
import requests
import time

SECRET = 'wJ5rX8pZ2kL9mN4qV7bA1cF3gH6jY0sD'
SERVER = 'http://YOUR_SERVER_IP:8080'

def deliver_rank(ign, uuid, product_id, product_name, price, group, duration=None, unit='days'):
    payload = {
        'event': 'order_delivered',
        'delivery_id': f'del_{int(time.time())}',
        'timestamp': int(time.time()),
        'player': {'username': ign, 'uuid': uuid},
        'product': {'id': product_id, 'name': product_name, 'price': price},
        'rank': {
            'group': group,
            'duration': {'value': duration, 'unit': unit} if duration else None,
            'permanent': duration is None
        },
        'commands': [
            f'lp user {player} parent addtemp {group} {duration}{unit}'
            if duration else
            f'lp user {player} parent add {group}'
        ]
    }

    resp = requests.post(
        f'{SERVER}/api/v1/delivery',
        json=payload,
        headers={'Authorization': f'Bearer {SECRET}'},
        timeout=10
    )
    return resp.json()

# Example
result = deliver_rank('Steve123', '8667ba71...', 'vip_rank', 'VIP', 4.99, 'vip', 30, 'days')
print(result)

bash# RankDelivery — cURL Example

# Temporary rank (30 days)
curl -X POST http://YOUR_SERVER_IP:8080/api/v1/delivery \
  -H "Authorization: Bearer wJ5rX8pZ2kL9mN4qV7bA1cF3gH6jY0sD" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "order_delivered",
  "delivery_id": "del_001",
  "timestamp": 1719999999,
  "player": { "username": "Steve123", "uuid": "8667ba71-..." },
  "product": { "id": "vip_rank", "name": "VIP", "price": 4.99 },
  "rank": { "group": "vip", "duration": { "value": 30, "unit": "days" } },
  "commands": [
    "lp user {player} parent addtemp {group} {duration}{unit}",
    "broadcast \u0026a{player} purchased {product}!"
  ]
}'

# Permanent rank (no duration)
curl -X POST http://YOUR_SERVER_IP:8080/api/v1/delivery \
  -H "Authorization: Bearer wJ5rX8pZ2kL9mN4qV7bA1cF3gH6jY0sD" \
  -H "Content-Type: application/json" \
  -d '{
  "delivery_id": "del_002",
  "timestamp": 1719999999,
  "player": { "username": "Steve123" },
  "rank": { "group": "vip", "permanent": true },
  "commands": [ "lp user {player} parent add {group}" ]
}'

Deliver Ranks Instantly From Your Web Store