StarkLayer¶

Remote monitoring endpoints used by the StarkLayer telemetry server (token-authed, public from a configured IP set).

All endpoints below are mounted under /api. Authentication: Authorization: Bearer <token> unless noted as public.

Endpoint count: 3

Endpoints¶

Method	Path	Handler	Guards
`GET`	`/api/starklayer/metrics`	`func`	-
`GET`	`/api/starklayer/ping`	`func`	-
`POST`	`/api/starklayer/push-license`	`func`	-

Source¶

Handlers for this section live in api/routes/handlers_*.go in the StarkOne source. Each handler binds its request body with gin.ShouldBindJSON(&req) and responds with the standard envelope:

{ "data": { ... } }

On error:

{ "error": { "code": "string", "message": "string" } }

Implementation note: these three StarkLayer endpoints are registered as inline closures in api/routes/routes.go (not named func handlers in handlers_*.go). They are exempt from the license-enforcement middleware and use a custom X-StarkLayer-Token header plus an optional IP allow-list rather than the standard JWT Authorization: Bearer flow or the { "data": ... } envelope.

Reference¶

`GET /api/starklayer/ping`¶

Returns the panel version, running status, and (if present) a summary of the active license - used by the StarkLayer telemetry server for version polling and health checks.

Guards: Optional shared-secret check against X-StarkLayer-Token (only enforced when StarkLayerToken is configured) plus an optional comma-separated IP allow-list (StarkLayerAllowIPs). Not a RequirePermission guard.

Request headers

Name	Required	Description
`X-StarkLayer-Token`	conditional	Must equal the server's configured `StarkLayerToken`. Only checked when that value is non-empty.

Response - 200 OK

The body is a flat object (not the { "data": ... } envelope). The license key is omitted entirely when no license is loaded.

{
  "version": "1.2.3",
  "status": "running",
  "license": {
    "key": "XXXX-XXXX-XXXX-XXXX",
    "tier": "pro",
    "status": "active",
    "expires_at": "2027-01-01T00:00:00Z",
    "max_websites": 50,
    "blocked": false
  }
}

Errors

Status	Code	Meaning
`401`	(flat `{"error":"unauthorized"}`)	`X-StarkLayer-Token` did not match the configured token.
`403`	(flat `{"error":"forbidden"}`)	Client IP is not in the configured `StarkLayerAllowIPs` allow-list.

These error bodies are flat ({"error":"..."}), not the coded {"error":{"code":...}} envelope.

Example

curl https://panel.example.com:2087/api/starklayer/ping \
  -H "X-StarkLayer-Token: $STARKLAYER_TOKEN"

`POST /api/starklayer/push-license`¶

Remotely activates a license key on the panel: short-circuits if the panel is already actively licensed, otherwise delegates to the internal license-activation logic.

Guards: Optional shared-secret check against X-StarkLayer-Token (only enforced when StarkLayerToken is configured). No IP allow-list is applied on this endpoint. Not a RequirePermission guard.

Request headers

Name	Required	Description
`X-StarkLayer-Token`	conditional	Must equal the server's configured `StarkLayerToken`. Only checked when that value is non-empty.

Request body

{ "license_key": "string (required)" }

Field	Type	Required	Description
`license_key`	string	yes	License key to activate. Bound with `binding:"required"`.

Response - 200 OK

Two distinct success shapes are possible:

If a valid active (non-blocked) license already exists, a flat short-circuit body is returned:

{ "status": "already_licensed", "tier": "pro" }

Otherwise the request is forwarded to the internal activation logic, which on success returns the standard envelope:

{
  "data": {
    "success": true,
    "features": { "feature_name": true },
    "tier": "pro",
    "status": "active"
  }
}

Errors

Status	Code	Meaning
`401`	(flat `{"error":"unauthorized"}`)	`X-StarkLayer-Token` did not match the configured token.
`400`	(flat `{"error":"<bind error>"}`)	Request body failed JSON binding (e.g. missing `license_key`).
`400`	`bad_request`	Body binding failed inside the delegated activation logic.
`400`	`activation_failed`	The license server rejected the activation.
`502`	`license_server_error`	The remote license server could not be reached or returned an invalid response.
`500`	`decode_error`	License data returned by the server could not be base64-decoded.
`500`	`write_error`	The decoded license file could not be written to disk.

The 400/401 errors raised directly by this endpoint are flat; the coded errors (bad_request, activation_failed, license_server_error, decode_error, write_error) originate from the delegated activateLicense logic and use the {"error":{"code":...,"message":...}} envelope.

Side effects

Calls the remote license server https://license.starkone.io/licensing/api/v2/activate/ (and queries https://api.ipify.org for the server's public IP) via the delegated activation logic.
On success, writes the decoded license blob to the license file path (mode 0600) and reloads the in-memory license state.

Example

curl -X POST https://panel.example.com:2087/api/starklayer/push-license \
  -H "X-StarkLayer-Token: $STARKLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"license_key": "XXXX-XXXX-XXXX-XXXX"}'

`GET /api/starklayer/metrics`¶

Returns the system metrics samples (CPU, memory, disk, disk I/O, network throughput) collected over the last 30 minutes.

Guards: Optional shared-secret check against X-StarkLayer-Token (only enforced when StarkLayerToken is configured). No IP allow-list is applied on this endpoint. Not a RequirePermission guard.

Request headers

Name	Required	Description
`X-StarkLayer-Token`	conditional	Must equal the server's configured `StarkLayerToken`. Only checked when that value is non-empty.

Response - 200 OK

A flat object with a metrics array (empty array when no samples exist). Each point uses the JSON field names below.

{
  "metrics": [
    {
      "ts": 1750000000,
      "cpu": 12.5,
      "mem_mb": 2048,
      "mem_total_mb": 8192,
      "disk_gb": 40,
      "disk_total_gb": 200,
      "disk_read": 1048576,
      "disk_write": 524288,
      "net_rx": 131072,
      "net_tx": 65536
    }
  ]
}

Field	Type	Description
`ts`	int64	Sample timestamp (Unix seconds).
`cpu`	float	CPU usage percentage.
`mem_mb`	uint	Memory used, MB.
`mem_total_mb`	uint	Total memory, MB.
`disk_gb`	uint	Disk used, GB.
`disk_total_gb`	uint	Total disk, GB.
`disk_read`	uint	Disk read throughput, bytes/sec.
`disk_write`	uint	Disk write throughput, bytes/sec.
`net_rx`	uint	Network receive throughput, bytes/sec.
`net_tx`	uint	Network transmit throughput, bytes/sec.

Errors

Status	Code	Meaning
`401`	(flat `{"error":"unauthorized"}`)	`X-StarkLayer-Token` did not match the configured token.
`500`	(flat `{"error":"<message>"}`)	Failed to query the metrics store.

Example

curl https://panel.example.com:2087/api/starklayer/metrics \
  -H "X-StarkLayer-Token: $STARKLAYER_TOKEN"

StarkLayer¶

Endpoints¶

Source¶

Reference¶

GET /api/starklayer/ping¶

POST /api/starklayer/push-license¶

GET /api/starklayer/metrics¶

`GET /api/starklayer/ping`¶

`POST /api/starklayer/push-license`¶

`GET /api/starklayer/metrics`¶