> ## Documentation Index
> Fetch the complete documentation index at: https://developer.leaderos.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Enable the Plugin API in the admin panel, get your API key and send your first request.

## 1. Enable the API

**1. Open the admin panel**

Sign in at `https://your-site.com/dashboard`. This page requires the **MANAGE\_SETTINGS** permission.

**2. Open Settings → API**

Turn on **API Status**. The change is saved immediately.

**3. Copy the API key**

Copy the value in the **API Key** field. You will use it in the plugin configuration and in your own integrations.

> [!NOTE]
>
> While the API is off or the key is empty, every `/api` request returns a **404 with an empty body**. If your plugin says it cannot connect, check this setting first.

## Panel settings

| Setting | Description |
| - | - |
| **API Status** | The master switch. While it is off, plugins, the Discord bot and every integration lose access to the site. |
| **API Key** | The secret key sent in the `X-Api-Key` header. Shown read-only in the panel. |
| **Reset** | Creates a new key. It sends you to leaderos.net and saves the new key after confirmation. |
| **Help** | Opens the help article for this page. |

> [!WARNING]
>
> When you reset the key, **everything that uses the old key stops working**: game-server plugins, the Discord bot and your own integrations. After a reset, update every `config` file with the new key and restart the servers. If you suspect the key has leaked, reset it right away.

> [!NOTE]
>
> The API key is also used with LeaderOS's external services (LeaderOS Connect, LeaderOS ID, LeaderOS AI). That is why the key is generated through leaderos.net rather than locally.

## 2. Your first request

```bash theme={null}
curl -H "X-Api-Key: YOUR_API_KEY" \
     "https://your-site.com/api/credits?username=Steve"
```

```json theme={null}
{ "credits": "150.00", "raw_credits": 150, "currency": "USD" }
```

A request with a form body:

```bash theme={null}
curl -X POST https://your-site.com/api/credits/add \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d "target_username=Steve" \
  -d "amount=25"
```

```json theme={null}
{ "status": true, "data": { "credits": "175.00", "raw_credits": 175, "currency": "USD" } }
```

> [!TIP]
>
> `curl -d` sends the body as `application/x-www-form-urlencoded` automatically. If you send JSON (`-H "Content-Type: application/json"`), validation fails and you get a `VALIDATION` error.

## 3. Security recommendations

* Keep the key on the server only (environment variable, `config` file on the server).
* Do not commit the key to Git; remove it before sharing `config` files.
* Nobody should see the key in game; do not print it in plugin messages or logs.
* If your provider supports it, add a firewall rule that only accepts API requests from your game server's IP (e.g. with Cloudflare).
* Reset the key when staff changes or whenever in doubt.

## Common errors

| Symptom | Cause | Fix |
| - | - | - |
| `404` with empty body | API is off or the key is empty | Turn it on in **Settings → API** |
| `401 INVALID_API_KEY` | Header missing or wrong key | Check the `X-Api-Key` header and value |
| `400 VALIDATION` | Required field missing or JSON was sent | Send form data, check the fields |
| `404 USER_NOT_FOUND` | Username/ID not found | On Minecraft sites the username must match **including case** |

## Next step

> [card] [Usage examples](https://developer.leaderos.net/plugin-api/en/usage.md)
>
> Call the API from your own plugin, bot or backend.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.