Panel/docs/features/USER_API.md

# User API

Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)

## Scope

This file documents the externally reachable API and webhook surfaces discovered in the repository.

Primary files:

- `Panel/ogp_api.php`
- `Panel/status_api.php`
- `Panel/sso.php`
- `Panel/modules/website/login.php`
- `Panel/modules/website/sso.php`
- `Panel/modules/website/order.php`

## Panel Automation API

Main endpoint:

- `Panel/ogp_api.php`

Transport:

- GET, POST, or JSON request body
- response is usually JSON
- `setting/get` returns plain text

Authentication:

- token-based
- token created through `token/create`
- host allowlist can be enforced with `api_authorized.hosts` and `api_authorized.fwd_hosts`

Important notes:

- the API is not a public anonymous API
- some routes are meaningful for normal users
- many routes are effectively admin-only because they mutate remote servers, create homes, or manage users

### Authentication Endpoints

| Endpoint | Auth | Purpose | Parameters | Returns |
|---|---|---|---|---|
| `ogp_api.php?token/create` | panel username/password | issue API token | `user`, `password` | JSON token payload |
| `ogp_api.php?token/test` | token | verify token | `token` | role/status |

### User-Visible Game Server Actions

| Endpoint | Auth | Purpose | Parameters | Returns |
|---|---|---|---|---|
| `gamemanager/start` | token + home access | start server | `ip`, `port`, optional `mod_key` | JSON status |
| `gamemanager/stop` | token + home access | stop server | `ip`, `port`, optional `mod_key` | JSON status |
| `gamemanager/restart` | token + home access | restart server | `ip`, `port`, optional `mod_key` | JSON status |
| `gamemanager/rcon` | token + home access | send RCON/console command | `ip`, `port`, optional `mod_key`, `command` | JSON command result |
| `gamemanager/update` | token + home access | update server | `ip`, `port`, optional `mod_key`, `type`, optional `manual_url` | JSON status |
| `litefm/list` | token + home access | list files | `ip`, `port`, `relative_path` | JSON listing |
| `litefm/get` | token + home access | read file | `ip`, `port`, `relative_path` | JSON file content |
| `litefm/save` | token + home access | write file | `ip`, `port`, `relative_path`, `contents` | JSON status |
| `litefm/remove` | token + home access | delete file | `ip`, `port`, `relative_path` | JSON status |
| `addonsmanager/list` | token | list add-on templates | `token` | JSON list |
| `addonsmanager/install` | token + home access | install named add-on | `ip`, `port`, `addon_id` | JSON status |
| `steam_workshop/install` | token + home access | legacy Workshop install | `ip`, `port`, optional `mod_key`, `mods_list` | JSON status |
| `server_content/run_scheduled_action` | token + home access | trigger typed server-content action | `home_id`, `action`, optional `options` | JSON status |

### Admin-Oriented API Routes

| Endpoint | Auth | Purpose | Parameters | Returns |
|---|---|---|---|---|
| `server/list` | admin token | list remote agents | `token` | JSON list |
| `server/status` | admin token | status of remote agent | `remote_server_id` | JSON status |
| `server/restart` | admin token | restart agent | `remote_server_id` | JSON status |
| `server/create` | admin token | create remote agent record | agent connection fields | JSON status |
| `server/remove` | admin token | remove remote agent record | `remote_server_id` | JSON status |
| `server/add_ip` | admin token | add IP to agent | `remote_server_id`, `ip` | JSON status |
| `server/remove_ip` | admin token | remove IP from agent | `remote_server_id`, `ip` | JSON status |
| `server/list_ips` | admin token | list assigned IPs | `remote_server_id` | JSON list |
| `server/edit_ip` | admin token | edit assigned IP | `remote_server_id`, `old_ip`, `new_ip` | JSON status |
| `user_games/list_games` | token | list game configs | `system`, `architecture` | JSON list |
| `user_games/list_servers` | token | list homes visible to token | none | JSON list |
| `user_games/create` | admin token | create game home | remote server, config, port, passwords, slots, affinity, nice | JSON status |
| `user_games/clone` | admin token | clone home | origin + new home fields | JSON status |
| `user_games/set_expiration` | admin token | change home expiry | `home_id`, `timestamp` | JSON status |
| `user_admin/*` | admin token | user CRUD and assignments | varies | JSON status |
| `gamemanager_admin/reorder` | admin token | reorder homes in UI | token | JSON status |
| `setting/get` | token | read setting | `setting_name` | plain text or `-1` |

## Public Status API

Endpoint:

- `Panel/status_api.php?token=...`

Authentication:

- shared query token stored in `status_api_local.php`

Purpose:

- public, read-only node summary
- intended for lightweight dashboards or public status pages

Behavior:

- caches agent stats locally for 30 seconds
- probes agents with TCP reachability
- normalizes CPU, memory, and disk stats when available

Returns:

- JSON object with `generated_at` and `nodes[]`

## Scheduler-As-API

The scheduler does not call agents directly at runtime. It stores cron lines on the agent that usually call back into:

- `Panel/ogp_api.php?gamemanager/*`
- `Panel/ogp_api.php?server_content/run_scheduled_action`

This makes `ogp_api.php` part of the internal scheduler runtime contract.

## Website Account And Order Entry

| Endpoint | Auth | Purpose | Parameters | Returns |
|---|---|---|---|---|
| `Panel/modules/website/login.php` | Panel user credentials | create a website session against the shared Panel user table | username/password form | website session and redirect |
| `Panel/modules/website/logout.php` | website session | destroy website session | none | redirect to website home |
| `Panel/modules/website/sso.php` | none | compatibility redirect for old SSO links | safe `destination` / `return` values | direct website or Panel redirect |
| `Panel/sso.php` | none | compatibility redirect for old Panel-to-website SSO links | safe `destination` / `return` values | direct website or Panel redirect |
| `Panel/modules/website/order.php` | anonymous website session | validate catalog service and configure order intent | `service_id`, slots/location POST | order page or cart redirect |
| `Panel/modules/website/cart.php` | anonymous website session; website login required only for checkout | review cart and begin checkout intent | cart actions | cart page or login redirect |

SSO is deferred in the current implementation because `gameservers.world` and `panel.iaregamer.com` cannot share one PHP session cookie. Users can use the same Panel-backed credentials on both sites, but website and Panel sessions are separate.

The old `Website/api/create_order.php`, `Website/api/capture_order.php`, `Website/api/log_error.php`, and `Website/webhook.php` compatibility files are not present in this repository checkout. Until an active payment runtime is connected, the website cart preserves validated order intent and displays a friendly checkout-unavailable message rather than claiming checkout is complete.

### Webhooks

| Endpoint | Source | Purpose | Auth Model |
|---|---|---|---|
| none active in this checkout | PayPal | payment processing must be reconnected before public checkout is enabled | document gateway-specific signature verification before use |

## Security Controls

| Control | Where |
|---|---|
| token auth | `Panel/ogp_api.php` |
| host allowlist | `api_authorized.hosts`, `api_authorized.fwd_hosts`, `settings/api_hosts.php` |
| role / ownership checks | inside `api_*` handlers in `ogp_api.php` |
| website session cart | `$_SESSION['website_cart']` |

## Search Coverage Used For This Document

- `rg -n "^function api_" Panel/ogp_api.php`
- `sed -n '1,240p' Panel/ogp_api.php`
- `sed -n '1,240p' Panel/status_api.php`
- `sed -n '1,220p' Panel/sso.php`
- `sed -n '1,220p' Panel/modules/website/sso.php`