Getting Started

Welcome to the CraftServerManager API documentation! This guide will help you get up and running with the API quickly.

Prerequisites

Before you begin, ensure you have:

• CraftServerManager plugin installed on your Minecraft server (1.21+)
• Java 17+ installed
• The HTTP API enabled in your config.yml

Configuration

1. Enable the API

Edit your plugins/CraftServerManager/config.yml:

# HTTP API Configuration
port: 8080
token: your-secure-token-here

# Enable CORS (for web applications)
cors:
  enabled: true
  allowed-origins: "*"

Security Note

Make sure to use a strong, unique token and keep it secure. This token is used for internal authentication between your services.

2. Restart Your Server

After configuring, restart your Minecraft server to apply changes:

/restart

The API will be available at http://your-server-ip:8080

Authentication

The API uses JWT (JSON Web Tokens) for authentication. Here's how to get started:

1. Register a User

First, a player needs to register in-game using the /register command. This generates a registration code.

2. Complete Web Registration

Use the registration code to create an account:

POST /api/auth/register
Content-Type: application/json

{
  "username": "player123",
  "password": "secure_password",
  "email": "player@example.com",
  "code": "ABC123"
}

3. Login

Once registered, login to receive a JWT token:

POST /api/auth/login
Content-Type: application/json

{
  "username": "player123",
  "password": "secure_password"
}

Response:

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

4. Use the Token

Include the token in the Authorization header for subsequent requests:

GET /api/auth/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Making Your First Request

Let's check your user information:

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

Successful response:

{
  "success": true,
  "username": "player123",
  "minecraftUsername": "Player123",
  "email": "player@example.com",
  "isAdmin": false,
  "isWhitelisted": true
}

API Base URL

All API endpoints are relative to your server's base URL:

http://your-server-ip:8080/api

For local development:

http://localhost:8080/api

Common Response Formats

Success Response

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error Response

{
  "success": false,
  "error": "Error message description"
}

HTTP Status Codes

The API uses standard HTTP status codes:

Code	Description
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
405	Method Not Allowed
500	Internal Server Error

Rate Limiting

INFO

Currently, the API does not enforce rate limiting, but this may be added in future versions. Please use the API responsibly.

CORS Support

Cross-Origin Resource Sharing (CORS) is enabled by default with the following headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

For production, consider restricting allowed-origins to specific domains.

Testing with Postman/Insomnia

You can import the following as a base collection:

Base URL: http://localhost:8080

Common Headers:

• Content-Type: application/json
• Authorization: Bearer YOUR_JWT_TOKEN

Next Steps

Now that you're set up, explore the API documentation:

• Authentication API - User registration and login
• Player API - Player management
• Economy API - Balance and transactions
• Shop API - Browse and purchase items
• Admin API - Administrative functions

Need Help?

• Check the API Reference for detailed endpoint documentation
• Visit our GitHub Issues for bug reports
• Join our community on Discord (if available)