# 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, SSO, 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?destination=panel` | website session | create a one-time token for Panel login | optional trusted return path | redirect to `Panel/sso.php` |
| `Panel/sso.php?token=...` | one-time SSO token | create normal Panel session | token | redirect to Panel page |
| `Panel/sso.php?destination=website` | Panel session | create a one-time token for website login | optional trusted return path | redirect to website SSO endpoint |
| `Panel/modules/website/sso.php?token=...` | one-time SSO token | create website session | token | redirect to website page |
| `Panel/modules/website/order.php` | website session for checkout continuation | validate catalog service and start order intent | `service_id` | order page or login redirect |

SSO tokens are stored in `OGP_DB_PREFIXsso_tokens` as SHA-256 hashes, expire in 30-60 seconds, and are marked used after successful validation. Tokens never contain passwords, password hashes, permanent API keys, or PHP session IDs.

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 order page validates service intent and sends customers to support 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` |
| one-time SSO token hash storage | `OGP_DB_PREFIXsso_tokens` |

## 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`