Whitelist API

Manage server whitelist entries programmatically.

Get Whitelist

Retrieve all whitelist entries.

Endpoint: GET /api/whitelist

Authentication: Required (JWT)

Success Response (200):

{
  "success": true,
  "whitelist": [
    {
      "username": "Player123",
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "addedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 1
}

Example:

curl http://localhost:8080/api/whitelist \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Add to Whitelist

Add a player to the server whitelist.

Endpoint: POST /api/whitelist/add

Authentication: Required (JWT, Admin)

Request Body:

{
  "username": "string (required, Minecraft username)"
}

Success Response (200):

{
  "success": true,
  "message": "Player added to whitelist",
  "username": "Player123"
}

Example:

curl -X POST http://localhost:8080/api/whitelist/add \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "Player123"}'

Error Responses:

• 400 - Missing username
• 403 - Admin privileges required
• 404 - Player not found

---

Remove from Whitelist

Remove a player from the server whitelist.

Endpoint: POST /api/whitelist/remove

Authentication: Required (JWT, Admin)

Request Body:

{
  "username": "string (required, Minecraft username)"
}

Success Response (200):

{
  "success": true,
  "message": "Player removed from whitelist",
  "username": "Player123"
}

Example:

curl -X POST http://localhost:8080/api/whitelist/remove \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "Player123"}'

---

Check Whitelist Status

Check if a player is whitelisted.

Endpoint: GET /api/whitelist/check?username=Player123

Authentication: Required (JWT)

Query Parameters:

• username - Minecraft username to check

Success Response (200):

{
  "success": true,
  "username": "Player123",
  "whitelisted": true
}

Example:

curl "http://localhost:8080/api/whitelist/check?username=Player123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Code Examples

TypeScript

class WhitelistAPI {
  constructor(private baseUrl: string, private token: string) {}
  
  async getWhitelist() {
    const response = await fetch(`${this.baseUrl}/api/whitelist`, {
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return await response.json();
  }
  
  async addPlayer(username: string) {
    const response = await fetch(`${this.baseUrl}/api/whitelist/add`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ username })
    });
    return await response.json();
  }
  
  async removePlayer(username: string) {
    const response = await fetch(`${this.baseUrl}/api/whitelist/remove`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ username })
    });
    return await response.json();
  }
  
  async checkPlayer(username: string) {
    const response = await fetch(
      `${this.baseUrl}/api/whitelist/check?username=${username}`,
      {
        headers: { 'Authorization': `Bearer ${this.token}` }
      }
    );
    return await response.json();
  }
}

Python

class WhitelistAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {'Authorization': f'Bearer {token}'}
    
    def get_whitelist(self):
        response = requests.get(
            f'{self.base_url}/api/whitelist',
            headers=self.headers
        )
        return response.json()
    
    def add_player(self, username):
        response = requests.post(
            f'{self.base_url}/api/whitelist/add',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json={'username': username}
        )
        return response.json()
    
    def remove_player(self, username):
        response = requests.post(
            f'{self.base_url}/api/whitelist/remove',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json={'username': username}
        )
        return response.json()
    
    def check_player(self, username):
        response = requests.get(
            f'{self.base_url}/api/whitelist/check',
            headers=self.headers,
            params={'username': username}
        )
        return response.json()

Notes

• Admin privileges required for add/remove operations
• Whitelist changes take effect immediately
• Players already online when removed will not be kicked
• Username checks are case-insensitive
• Invalid usernames will return 404

Related

• Admin API - Other admin operations
• Players API - Player management