Authentication API

User registration, login, and session management endpoints.

Register New User

Create a new user account linked to a Minecraft player.

Endpoint: POST /api/auth/register

Authentication: None required

Request Body:

{
  "username": "string (required)",
  "password": "string (required, min 6 characters)",
  "email": "string (required, valid email)",
  "code": "string (required, registration code from in-game)"
}

Success Response (201):

{
  "success": true,
  "message": "Registration successful"
}

Example:

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "player123",
    "password": "secure_password",
    "email": "player@example.com",
    "code": "ABC123"
  }'

Error Responses:

• 400 - Invalid input (missing fields, weak password, invalid email)
• 400 - Invalid or expired registration code
• 409 - Username already exists

---

Login

Authenticate and receive a JWT token.

Endpoint: POST /api/auth/login

Authentication: None required

Request Body:

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

Success Response (200):

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "player123",
  "minecraftUsername": "Player123",
  "isAdmin": false
}

Example:

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "player123",
    "password": "secure_password"
  }'

Error Responses:

• 400 - Missing username or password
• 401 - Invalid credentials
• 500 - Server error

---

Get Current User

Get information about the currently authenticated user.

Endpoint: GET /api/auth/me

Authentication: Required (JWT)

Success Response (200):

{
  "success": true,
  "username": "player123",
  "minecraftUsername": "Player123",
  "email": "player@example.com",
  "isAdmin": false,
  "isWhitelisted": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Example:

curl -X GET http://localhost:8080/api/auth/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Responses:

• 401 - Invalid or missing token
• 403 - Token expired

---

Verify Registration Code

Verify if a registration code is valid before creating an account.

Endpoint: POST /api/auth/verify-code

Authentication: None required

Request Body:

{
  "code": "string (required)"
}

Success Response (200):

{
  "success": true,
  "valid": true,
  "minecraftUsername": "Player123"
}

Invalid Code Response (200):

{
  "success": true,
  "valid": false
}

Example:

curl -X POST http://localhost:8080/api/auth/verify-code \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ABC123"
  }'

Error Responses:

• 400 - Missing code parameter

---

Code Examples

JavaScript/TypeScript

interface LoginCredentials {
  username: string;
  password: string;
}

interface LoginResponse {
  success: boolean;
  token: string;
  username: string;
  minecraftUsername: string;
  isAdmin: boolean;
}

async function login(credentials: LoginCredentials): Promise<LoginResponse> {
  const response = await fetch('http://localhost:8080/api/auth/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(credentials)
  });
  
  if (!response.ok) {
    throw new Error(`Login failed: ${response.statusText}`);
  }
  
  return await response.json();
}

// Usage
const token = await login({
  username: 'player123',
  password: 'secure_password'
});
console.log('Logged in:', token.minecraftUsername);

Python

import requests

def register_user(username, password, email, code):
    response = requests.post(
        'http://localhost:8080/api/auth/register',
        json={
            'username': username,
            'password': password,
            'email': email,
            'code': code
        }
    )
    return response.json()

def login(username, password):
    response = requests.post(
        'http://localhost:8080/api/auth/login',
        json={'username': username, 'password': password}
    )
    data = response.json()
    if data['success']:
        return data['token']
    raise Exception(data.get('error', 'Login failed'))

def get_user_info(token):
    response = requests.get(
        'http://localhost:8080/api/auth/me',
        headers={'Authorization': f'Bearer {token}'}
    )
    return response.json()

# Usage
token = login('player123', 'secure_password')
user_info = get_user_info(token)
print(f"Logged in as: {user_info['minecraftUsername']}")

Java

import java.net.http.*;
import java.net.URI;
import com.google.gson.Gson;

public class AuthClient {
    private static final String BASE_URL = "http://localhost:8080/api";
    private final HttpClient client = HttpClient.newHttpClient();
    private final Gson gson = new Gson();
    
    public String login(String username, String password) throws Exception {
        String json = gson.toJson(Map.of(
            "username", username,
            "password", password
        ));
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/auth/login"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
        
        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );
        
        // Parse response and return token
        Map<String, Object> data = gson.fromJson(
            response.body(),
            Map.class
        );
        return (String) data.get("token");
    }
}

Notes

• Registration codes are generated in-game using the /register command
• Codes expire after 24 hours by default
• Passwords must be at least 6 characters
• JWT tokens are valid for 24 hours
• Tokens include user role and permissions
• Store tokens securely (httpOnly cookies recommended for web apps)

Related

• Authentication Overview - JWT concepts and security
• Getting Started - Initial setup
• Admin API - Admin-only endpoints