Sections

Introduction Authentication Response format Servers Rate limits Support

Beacon panel · REST

Automation-friendly API reference

Base path /api/v1 with bearer-authenticated workloads you can curl, pipeline in CI, or integrate with your control plane tooling.

Introduction

The Beacon Panel API allows you to programmatically manage your game servers, databases, files, schedules, backups, and more. This documentation sketches every generated route bundle, authentication expectations, and request/response examples.

All endpoints are rooted at /api/v1 unless denoted otherwise, and Bearer tokens gate access.

Authentication

Attach a Bearer credential on every authenticated verb:

Header

Authorization: Bearer YOUR_TOKEN_HERE

Obtaining a token

Mint API keys inside account settings inside the Beacon panel UI. Tokens mirror your RBAC posture — revoke and rotate aggressively if they leak.

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Response format

Payloads converge on one envelope irrespective of verb family:

{
"success": true|false,
"data": {}, // Only present on success
"error": "Error message" // Only present on failure
}

Success example

{
"success": true,
"data": {
  "id": "servers/123",
  "name": "Minecraft Server",
  "status": "running"
}
}

Error example

{
"success": false,
"error": "Server not found"
}

HTTP status codes

Status	Description
200 OK	Request succeeded with a usable payload or empty success envelope.
400 Bad Request	Validator rejected malformed input or missing required keys.
401 Unauthorized	Bearer token absent, malformed, or expired.
403 Forbidden	Identity valid but forbidden for that resource/action tuple.
404 Not Found	Unknown UUID, wiped server row, or out-of-scope identifier.
429 Too Many Requests	Exhausted quotas — backoff using rate-limit headers.
500 Internal Server Error	Unexpected stack path — escalate with correlation IDs/timestamps.

Servers

Fetch detailed information about a single server.

GET/api/v1/servers/{serverId}

Fetch detailed information about a single server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
action	string	No	The action to perform

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "id": "servers/123",
    "name": "Example server",
    "status": "running"
  }
}

Send a power action (start/stop/restart/kill) to a server.

POST/api/v1/servers/{serverId}

Send a power action (start/stop/restart/kill) to a server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
action	string	Yes	Power action to perform. One of: "start", "stop", "restart", "kill".

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "action": "restart"
}'

Example response

{
  "success": true,
  "data": {
    "message": "Power action enqueued."
  }
}

List all servers visible to the authenticated user.

GET/api/v1/servers

List all servers visible to the authenticated user.

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": [
    {
      "id": "servers/123",
      "name": "Example server",
      "status": "running"
    }
  ]
}

Backups

Generate a signed download URL for a server backup.

GET/api/v1/servers/{serverId}/backups/{backup}/download

Generate a signed download URL for a server backup.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
backup	string	Yes	The backup identifier to download.

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/backups/{backup}/download" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "link": "https://example-node/download/backup?token=..."
  }
}

Fetch metadata for a single server backup.

GET/api/v1/servers/{serverId}/backups/{backup}

Fetch metadata for a single server backup.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
backup	string	Yes	The backup identifier.

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/backups/{backup}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "backupId": "bkp-123",
    "name": "Nightly backup",
    "size": 123456789,
    "completedAt": 1720000000000,
    "locked": false
  }
}

Delete a single server backup.

DELETE/api/v1/servers/{serverId}/backups/{backup}

Delete a single server backup.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
backup	string	Yes	The backup identifier to delete.

Example request

cURL

curl -X DELETE "https://www.beaconhosting.org/api/v1/servers/{serverId}/backups/{backup}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "message": "Backup deleted."
  }
}

List all backups for a specific server.

GET/api/v1/servers/{serverId}/backups

List all backups for a specific server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
name	string	No	The name parameter
ignored	string	No	The ignored parameter

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/backups" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": [
    {
      "backupId": "bkp-123",
      "name": "Nightly backup",
      "size": 123456789,
      "completedAt": 1720000000000,
      "locked": false
    }
  ]
}

Create a new backup for a server.

POST/api/v1/servers/{serverId}/backups

Create a new backup for a server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
name	string	No	Optional human-readable name for the backup (defaults to "API Backup").
ignored	string	No	Optional newline-delimited list of paths to exclude from the backup.

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/backups" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "name": "Manual API backup",
  "ignored": "cache\nlogs"
}'

Example response

{
  "success": true,
  "data": {
    "message": "Backup created."
  }
}

Console

Fetch recent console log lines from a server.

GET/api/v1/servers/{serverId}/console

Fetch recent console log lines from a server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Query parameters

Parameter	Type	Required	Description
size	number	No	Number of log lines to return (defaults to 100, capped at 1000).

Request body

Parameter	Type	Required	Description
command	string	No	The command to execute

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/console" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Send a console command to a server.

POST/api/v1/servers/{serverId}/console

Send a console command to a server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Query parameters

Parameter	Type	Required	Description
size	string	No	Number of items to return

Request body

Parameter	Type	Required	Description
command	string	Yes	The console command to execute on the target server (e.g. `say Hello from the API!`).

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/console" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "command": "say Hello from the API!"
}'

Databases

Rotate the password for a specific server database.

POST/api/v1/servers/{serverId}/databases/{database}/rotate-password

Rotate the password for a specific server database.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
database	string	Yes	The database name whose password should be rotated.

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/databases/{database}/rotate-password" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "message": "Database password rotated."
  }
}

Delete a single database belonging to a server.

DELETE/api/v1/servers/{serverId}/databases/{database}

Delete a single database belonging to a server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
database	string	Yes	The database name to delete.

Example request

cURL

curl -X DELETE "https://www.beaconhosting.org/api/v1/servers/{serverId}/databases/{database}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "message": "Database deleted."
  }
}

List databases attached to a specific server.

GET/api/v1/servers/{serverId}/databases

List databases attached to a specific server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
database	string	No	The database name

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/databases" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": [
    {
      "name": "beacon_panel",
      "host": "db.example.local",
      "port": 3306,
      "username": "panel_user"
    }
  ]
}

Create a new database for a server.

POST/api/v1/servers/{serverId}/databases

Create a new database for a server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
database	string	Yes	The name of the database to create (must be a non-empty string).

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/databases" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "database": "example_database"
}'

Example response

{
  "success": true,
  "data": {
    "message": "Database created."
  }
}

Files

Compress multiple files or directories on a server into an archive.

POST/api/v1/servers/{serverId}/files/compress

Compress multiple files or directories on a server into an archive.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
files	array	Yes	Array of file or directory paths (relative to `root`) to include in the archive.
root	string	No	Base directory for the operation (defaults to `/` when omitted).

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/compress" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "files": [
    "logs/latest.log",
    "world"
  ],
  "root": "/"
}'

Example response

{
  "success": true,
  "data": {
    "message": "Compression requested."
  }
}

Read the contents of a file on the server.

GET/api/v1/servers/{serverId}/files/contents

Read the contents of a file on the server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Query parameters

Parameter	Type	Required	Description
file	string	Yes	Path to the file relative to the server root (e.g. `server.properties`).
download	boolean	No	When `true`, return a download response instead of inline content (subject to trial/export rules).

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/contents" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "content": "example=value\nanother=setting"
  }
}

Copy a file or directory on the server.

POST/api/v1/servers/{serverId}/files/copy

Copy a file or directory on the server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
from	string	Yes	Source file or directory path to copy (relative to the server root).
to	string	Yes	Destination path for the copy (relative to the server root).

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/copy" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "from": "/world",
  "to": "/world-backup"
}'

Example response

{
  "success": true,
  "data": {
    "message": "Copy requested."
  }
}

Create a folder within the server's filesystem.

POST/api/v1/servers/{serverId}/files/create-folder

Create a folder within the server's filesystem.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
name	string	Yes	Name of the folder to create.
path	string	No	Base path where the folder should be created (defaults to `/`).

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/create-folder" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "name": "config",
  "path": "/plugins/"
}'

Example response

{
  "success": true,
  "data": {
    "message": "Folder created."
  }
}

Extract an archive on the server into a target directory.

POST/api/v1/servers/{serverId}/files/decompress

Extract an archive on the server into a target directory.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
file	string	Yes	Path to the archive file to decompress (relative to the server root).
root	string	No	Base directory where the archive should be extracted (defaults to `/`).

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/decompress" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "file": "/backups/world.zip",
  "root": "/"
}'

Example response

{
  "success": true,
  "data": {
    "message": "Decompression requested."
  }
}

Delete a file from the server (moves to trash by default; permanently deletes if already in `.trash`).

POST/api/v1/servers/{serverId}/files/delete

Delete a file from the server (moves to trash by default; permanently deletes if already in `.trash`).

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
file	string	Yes	Path to the file to delete, relative to the server root.

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/delete" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "file": "/logs/latest.log"
}'

Example response

{
  "success": true,
  "data": {
    "message": "File deleted."
  }
}

Generate a download URL for a file on the server.

GET/api/v1/servers/{serverId}/files/download

Generate a download URL for a file on the server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Query parameters

Parameter	Type	Required	Description
file	string	Yes	Path to the file to download, relative to the server root.

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/download" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "url": "/api/servers/123/files/download?file=%2Flogs%2Flatest.log"
  }
}

List files and folders in a directory on the server.

GET/api/v1/servers/{serverId}/files/list

List files and folders in a directory on the server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Query parameters

Parameter	Type	Required	Description
directory	string	No	Directory to list, relative to the server root (defaults to `/`).

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/list" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "files": [
      {
        "name": "logs",
        "directory": true
      },
      {
        "name": "server.properties",
        "directory": false,
        "size": 2048
      }
    ]
  }
}

Rename or move a file or directory on the server.

PUT/api/v1/servers/{serverId}/files/rename

Rename or move a file or directory on the server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
from	string	Yes	Source file or directory path to rename/move (relative to `/`).
to	string	Yes	Destination path for the renamed/moved file or directory.

Example request

cURL

curl -X PUT "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/rename" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "from": "/server.properties",
  "to": "/server.properties.bak"
}'

Example response

{
  "success": true,
  "data": {
    "message": "Rename requested."
  }
}

Issue a short-lived JWT and upload URL for direct file upload to the node.

POST/api/v1/servers/{serverId}/files/upload

Issue a short-lived JWT and upload URL for direct file upload to the node.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/upload" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "uploadUrl": "/api/v1/servers/123/files/upload-direct",
    "instructions": "Use this JWT in the Authorization header (Bearer token) when uploading files to the uploadUrl. The upload should be a multipart/form-data request with the file in the 'files' field."
  }
}

Write or overwrite a file on the server with the provided content.

POST/api/v1/servers/{serverId}/files/write

Write or overwrite a file on the server with the provided content.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
file	string \| { name: string }	Yes	File path as a string, or an object with a `name` property containing the full path.
content	string	Yes	Text content to write into the file.

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/write" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "file": "/server.properties",
  "content": "motd=Hello from the API!\n"
}'

Example response

{
  "success": true,
  "data": {
    "message": "File written successfully"
  }
}

Network

Promote a specific allocation to be the server's primary IP/port.

POST/api/v1/servers/{serverId}/network/allocations/{allocation}/primary

Promote a specific allocation to be the server's primary IP/port.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
allocation	number	Yes	Port number of the allocation to mark as primary (must be a positive integer).

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/network/allocations/{allocation}/primary" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "message": "Primary allocation updated."
  }
}

Update metadata (e.g. notes) for a specific network allocation.

POST/api/v1/servers/{serverId}/network/allocations/{allocation}

Update metadata (e.g. notes) for a specific network allocation.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
allocation	number	Yes	Port number of the allocation to annotate (must be a positive integer).

Request body

Parameter	Type	Required	Description
notes	string	No	Optional notes to associate with this allocation.

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/network/allocations/{allocation}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "notes": "Primary game port for EU players."
}'

Example response

{
  "success": true,
  "data": {
    "port": 25565,
    "notes": "Primary game port for EU players."
  }
}

Remove a specific network allocation (IP/port) from the server.

DELETE/api/v1/servers/{serverId}/network/allocations/{allocation}

Remove a specific network allocation (IP/port) from the server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
allocation	number	Yes	Port number of the allocation to remove (must be a positive integer).

Request body

Parameter	Type	Required	Description
notes	string	No	The notes parameter

Example request

cURL

curl -X DELETE "https://www.beaconhosting.org/api/v1/servers/{serverId}/network/allocations/{allocation}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "message": "Allocation removed."
  }
}

List all network allocations (IP/port pairs) for a server.

GET/api/v1/servers/{serverId}/network/allocations

List all network allocations (IP/port pairs) for a server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/network/allocations" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": [
    {
      "ip": "192.0.2.10",
      "port": 25565,
      "primary": true
    }
  ]
}

Allocate an additional IP/port for the server according to node policies.

POST/api/v1/servers/{serverId}/network/allocations

Allocate an additional IP/port for the server according to node policies.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/network/allocations" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "message": "Allocation created."
  }
}

Permissions

Return the effective permission set the current user has for this server.

GET/api/v1/servers/{serverId}/permissions

Return the effective permission set the current user has for this server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/permissions" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "hasAccess": true,
    "permissions": [
      "CONSOLE_SEND",
      "FILE_READ",
      "FILE_WRITE"
    ]
  }
}

Settings

Return resource limits and basic status for a single server (databases, allocations, backups, schedules).

GET/api/v1/servers/{serverId}/settings/resources

Return resource limits and basic status for a single server (databases, allocations, backups, schedules).

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/settings/resources" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "databases": {
      "limit": 2,
      "current": 1
    },
    "allocations": {
      "limit": 3,
      "current": 1
    },
    "backups": {
      "limit": 5,
      "current": 2
    },
    "schedules": {
      "limit": 1,
      "current": 0
    },
    "server": {
      "status": "running",
      "name": "Example server"
    }
  }
}

Users

Fetch details for a specific server subuser.

GET/api/v1/servers/{serverId}/users/{subuser}

Fetch details for a specific server subuser.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
subuser	string	Yes	Subuser identifier (subuser id or underlying user id depending on implementation).

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/users/{subuser}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "id": "subuser-1",
    "userId": "users/123",
    "email": "player@example.com",
    "permissions": [
      "CONSOLE_SEND",
      "FILE_READ"
    ]
  }
}

Update the permissions granted to a specific server subuser.

POST/api/v1/servers/{serverId}/users/{subuser}

Update the permissions granted to a specific server subuser.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
subuser	string	Yes	Subuser identifier whose permissions will be updated.

Request body

Parameter	Type	Required	Description
permissions	string[]	Yes	Array of permission codes to grant this subuser.

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/users/{subuser}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "permissions": [
    "CONSOLE_SEND",
    "FILE_READ"
  ]
}'

Example response

{
  "success": true,
  "data": {
    "message": "Subuser permissions updated."
  }
}

Remove a subuser from a server.

DELETE/api/v1/servers/{serverId}/users/{subuser}

Remove a subuser from a server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.
subuser	string	Yes	Subuser identifier to remove.

Example request

cURL

curl -X DELETE "https://www.beaconhosting.org/api/v1/servers/{serverId}/users/{subuser}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": {
    "message": "Subuser removed."
  }
}

List all subusers for a server, including their emails and permissions.

GET/api/v1/servers/{serverId}/users

List all subusers for a server, including their emails and permissions.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Example request

cURL

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/users" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example response

{
  "success": true,
  "data": [
    {
      "id": "subuser-1",
      "userId": "users/123",
      "email": "player@example.com",
      "permissions": [
        "CONSOLE_SEND",
        "FILE_READ"
      ]
    }
  ]
}

Create a new subuser for a server.

POST/api/v1/servers/{serverId}/users

Create a new subuser for a server.

Path parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server.

Request body

Parameter	Type	Required	Description
userEmail	string	Yes	Email address of the user to invite as a subuser.
permissions	string[]	Yes	Array of permission codes to grant this subuser.

Example request

cURL

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/users" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "userEmail": "player@example.com",
  "permissions": [
    "CONSOLE_SEND",
    "FILE_READ"
  ]
}'

Example response

{
  "success": true,
  "data": {
    "message": "Subuser created."
  }
}

Rate limiting

The public API is designed for normal panel usage and automation — we do not currently enforce hard per-key quotas. For typical control-plane workloads you should not see 429 Too Many Requests responses.

We reserve the right to throttle or block clearly abusive traffic (for example, tight loops hammering a single endpoint), but there is no published "Standard vs Enterprise" rate tier to stay under. If you're planning sustained high-throughput usage, open a support ticket so we can sanity-check the pattern and keep an eye on it.

If we ever introduce formal rate limits in front of this API, this section will be updated with concrete numbers and any relevant rate-limit headers.

Support

If anything here is confusing, inaccurate, or behaving oddly in your environment, talk directly to the Beacon team

API & documentation feedback

Spotted a mismatch between the API and these docs, or need an example we haven't covered yet? Open a ticket and we'll adjust the documentation and, if needed, the endpoint itself.

Open a support ticket →

Operational support

For production incidents or help wiring the API into your tooling, open a ticket from your Beacon account so we can tie context to your servers and respond quickly.

Open a support ticket →