From 3a074b123fa96fdac1f594da48507b2c85055123 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sun, 12 Apr 2026 13:38:07 +0000 Subject: [PATCH] Document admin bypass on instance routes and always-enabled runtime controls Generated-By: mintlify-agent --- api-reference/agents.mdx | 49 +++++++++++-------------- api-reference/maintenance.mdx | 67 ++++++++++++++++------------------- 2 files changed, 51 insertions(+), 65 deletions(-) diff --git a/api-reference/agents.mdx b/api-reference/agents.mdx index 6741621..f37fa9b 100644 --- a/api-reference/agents.mdx +++ b/api-reference/agents.mdx @@ -7,7 +7,7 @@ description: "Create, manage, and interact with agents" Create, manage, and interact with agents. -All agent endpoints that require authentication are scoped to the authenticated user's data through [row-level security](/security#row-level-security). You can only access agents that belong to your account. +All agent endpoints that require authentication are scoped to the authenticated user's data through [row-level security](/security#row-level-security). You can only access agents that belong to your account. Admin users (configured via `ADMIN_EMAILS`) bypass ownership checks on instance and backend agent routes, allowing them to operate on any user's agent or instance for recovery and support purposes. ## List agents @@ -178,7 +178,7 @@ The web proxy wraps the agent in an object: | Code | Description | |------|-------------| | 401 | Unauthorized | -| 403 | Forbidden — you do not own this agent. Returned when the agent has an `ownerEmail` set and it does not match the authenticated user's email. Admins bypass this check. | +| 403 | Forbidden — the caller does not own this agent and is not an admin. Returned when the agent has an `ownerEmail` set and it does not match the authenticated user's email. Admin users (configured via `ADMIN_EMAILS`) bypass this check. | | 404 | Agent not found — no container or metadata exists for this agent ID | | 500 | Failed to fetch agent | @@ -889,8 +889,8 @@ Agent status is reported across multiple endpoints. The following table lists al Lifecycle operations are available at two endpoint patterns depending on which service you call: -- **Web proxy:** `/api/instance/:userId/{action}` — requires session authentication and proxies to the backend. -- **Backend direct:** `/api/agents/:id/{action}` — requires API key authentication. +- **Web proxy:** `/api/instance/:userId/{action}` — requires session authentication and instance ownership. Admin users bypass the ownership check and can act on any user's instance. +- **Backend direct:** `/api/agents/:id/{action}` — requires API key authentication and ownership. Admin users bypass the ownership check. Both patterns support the same actions. The examples below show both response shapes where they differ. @@ -927,10 +927,10 @@ Starts a stopped agent container using `docker start`. | Code | Source | Description | |------|--------|-------------| | 401 | Both | Unauthorized — missing or invalid authentication | -| 403 | Both | Forbidden — you do not own this agent | +| 403 | Both | Forbidden — the caller does not own this agent and is not an admin | | 404 | Backend | Agent not found | | 500 | Both | Start failed | -| 503 | Web proxy | Managed runtime controls are disabled, or service/config resolution failed | +| 503 | Web proxy | Service/config resolution failed | ### Stop agent @@ -963,10 +963,10 @@ Stops the agent container using `docker stop`. The container retains its data an | Code | Source | Description | |------|--------|-------------| | 401 | Both | Unauthorized — missing or invalid authentication | -| 403 | Both | Forbidden — you do not own this agent | +| 403 | Both | Forbidden — the caller does not own this agent and is not an admin | | 404 | Backend | Agent not found | | 500 | Both | Stop failed | -| 503 | Web proxy | Managed runtime controls are disabled, or service/config resolution failed | +| 503 | Web proxy | Service/config resolution failed | ### Restart agent @@ -1006,10 +1006,10 @@ POST /api/agents/:id/restart | Code | Source | Description | |------|--------|-------------| | 401 | Both | Unauthorized — missing or invalid authentication | -| 403 | Both | Forbidden — you do not own this agent | +| 403 | Both | Forbidden — the caller does not own this agent and is not an admin | | 404 | Backend | Agent not found | | 500 | Both | Restart failed | -| 503 | Web proxy | Managed runtime controls are disabled, or service/config resolution failed | +| 503 | Web proxy | Service/config resolution failed | ### Update agent image @@ -1068,10 +1068,10 @@ Triggers an image update on the backend. Before replacing the service, the endpo |------|--------|-------------| | 400 | Backend | Invalid docker image value | | 401 | Both | Unauthorized — missing or invalid authentication | -| 403 | Both | Forbidden — you do not own this agent | +| 403 | Both | Forbidden — the caller does not own this agent and is not an admin | | 404 | Backend | Agent not found | | 500 | Both | Update failed. When automatic rollback succeeds on the backend, the agent continues running on the previous image. | -| 503 | Web proxy | Managed runtime controls are disabled, or service/config resolution failed | +| 503 | Web proxy | Service/config resolution failed | ### Repair agent @@ -1106,10 +1106,10 @@ Repairs an agent by reconfiguring its environment and restarting the service. | Code | Source | Description | |------|--------|-------------| | 401 | Both | Unauthorized — missing or invalid authentication | -| 403 | Both | Forbidden — you do not own this agent | +| 403 | Both | Forbidden — the caller does not own this agent and is not an admin | | 404 | Backend | Agent not found | | 500 | Both | Repair failed | -| 503 | Web proxy | Managed runtime controls are disabled, or service/config resolution failed | +| 503 | Web proxy | Service/config resolution failed | ### Reset agent memory @@ -1140,10 +1140,10 @@ POST /api/agents/:id/reset-memory | Code | Source | Description | |------|--------|-------------| | 401 | Both | Unauthorized — missing or invalid authentication | -| 403 | Both | Forbidden — you do not own this agent | +| 403 | Both | Forbidden — the caller does not own this agent and is not an admin | | 404 | Backend | Agent not found | | 500 | Both | Reset failed | -| 503 | Web proxy | Managed runtime controls are disabled, or service/config resolution failed | +| 503 | Web proxy | Service/config resolution failed | ### Lifecycle error responses @@ -1173,16 +1173,7 @@ The update endpoint is the exception and returns: } ``` -All web proxy lifecycle endpoints return `503` when managed runtime controls are disabled or when the platform cannot resolve the agent's service configuration: - -```json -{ - "success": false, - "error": "Managed runtime controls are temporarily disabled until the Railway control path is fully verified." -} -``` - -When service or configuration resolution fails, the error message describes the specific issue: +All web proxy lifecycle endpoints return `503` when the platform cannot resolve the agent's service configuration. The error message describes the specific issue: ```json { @@ -1191,14 +1182,16 @@ When service or configuration resolution fails, the error message describes the } ``` +Managed runtime controls are always enabled. The controls flag is hardcoded to `true` and can no longer be disabled via environment variables. + | Code | Source | Description | |------|--------|-------------| | 401 | Both | Unauthorized — missing or invalid authentication | -| 403 | Both | Forbidden — authenticated user does not own this agent. The backend returns `{ "error": "Forbidden — you do not own this agent" }`. The web proxy returns `{ "success": false, "error": "..." }`. | +| 403 | Both | Forbidden — the caller does not own this agent and is not an admin. The backend returns `{ "error": "Forbidden — you do not own this agent" }`. The web proxy returns `{ "success": false, "error": "..." }`. Admin users bypass this check. | | 404 | Backend | Agent not found — no metadata exists for this agent ID | | 500 | Both | The lifecycle action failed. On the backend, this means the Docker command or Railway mutation failed. On the web proxy, this means the Railway API call succeeded in resolving the service but the mutation itself failed. | | 502 | Web proxy | Backend service unavailable | -| 503 | Web proxy | Managed runtime controls are disabled, or the platform could not resolve the agent's managed service. This applies to all lifecycle actions: start, stop, restart, update, repair, and reset-memory. See [503 error details](/api-reference/maintenance#503-error-details) for the full list of possible error messages. | +| 503 | Web proxy | The platform could not resolve the agent's managed service. This applies to all lifecycle actions: start, stop, restart, update, repair, and reset-memory. See [503 error details](/api-reference/maintenance#503-error-details) for the full list of possible error messages. | ## Get instance details diff --git a/api-reference/maintenance.mdx b/api-reference/maintenance.mdx index a992957..2d6be25 100644 --- a/api-reference/maintenance.mdx +++ b/api-reference/maintenance.mdx @@ -7,13 +7,15 @@ description: "Agent health monitoring, restart, instance state, and factory rese Check agent health, query runtime state, and trigger maintenance restarts. These endpoints operate on the authenticated user's deployed agent instance. +Admin users (configured via `ADMIN_EMAILS`) can access any user's instance through all `/api/instance/:userId` endpoints. When an admin calls these endpoints, the ownership check is bypassed and the target user is resolved by looking up the provided `userId` as an `openclawInstanceId` in the database. Regular users can only access their own instance. + ## Get instance runtime state ```http GET /api/instance/:userId ``` -Requires session authentication. Returns runtime state for a specific agent instance by probing the agent's `/healthz` and `/readyz` endpoints directly. This endpoint resolves status without a backend hop — it reads the persisted OpenClaw URL from the database and probes the agent in-process. +Requires session authentication and instance ownership. Admin users bypass the ownership check and can query any user's instance. Returns runtime state for a specific agent instance by probing the agent's `/healthz` and `/readyz` endpoints directly. This endpoint resolves status without a backend hop — it reads the persisted OpenClaw URL from the database and probes the agent in-process. ### Path parameters @@ -68,7 +70,7 @@ Requires session authentication. Returns runtime state for a specific agent inst | Code | Description | |------|-------------| | 403 | Forbidden — not authenticated (no valid session) | -| 404 | No instance found — the authenticated user does not have a deployed agent, or does not own the requested instance. The response message is: `No instance found. Please deploy first.` | +| 404 | No instance found — the user does not have a deployed agent, or the caller does not own the requested instance and is not an admin. The response message is: `No instance found. Please deploy first.` | --- @@ -78,7 +80,7 @@ Requires session authentication. Returns runtime state for a specific agent inst GET /api/instance/:userId/stats ``` -Requires session authentication and instance ownership. Returns runtime stats for a specific agent instance by probing the agent's gateway. Resource-level metrics (CPU, memory) are not yet exposed by the gateway and return placeholder values. +Requires session authentication and instance ownership. Admin users bypass the ownership check and can query any user's instance. Returns runtime stats for a specific agent instance by probing the agent's gateway. Resource-level metrics (CPU, memory) are not yet exposed by the gateway and return placeholder values. ### Path parameters @@ -130,7 +132,7 @@ Requires session authentication and instance ownership. Returns runtime stats fo | Code | Description | |------|-------------| | 401 | Unauthorized — no valid session | -| 403 | Forbidden — the authenticated user does not own the requested instance | +| 403 | Forbidden — the caller does not own the requested instance and is not an admin | --- @@ -140,7 +142,7 @@ Requires session authentication and instance ownership. Returns runtime stats fo POST /api/instance/:userId/start ``` -Requires session authentication and instance ownership. Triggers a deploy of the user's agent service on Railway. When managed runtime controls are disabled, this endpoint returns `503`. +Requires session authentication and instance ownership. Admin users bypass the ownership check and can start any user's instance. Triggers a deploy of the user's agent service on Railway. ### Path parameters @@ -162,9 +164,9 @@ Requires session authentication and instance ownership. Triggers a deploy of the | Code | Description | |------|-------------| | 401 | Unauthorized — no valid session | -| 403 | Forbidden — the authenticated user does not own the requested instance | +| 403 | Forbidden — the caller does not own the requested instance and is not an admin | | 500 | Failed to start the service (for example, the Railway deploy mutation failed) | -| 503 | Managed runtime controls are disabled, or service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | +| 503 | Service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | --- @@ -174,7 +176,7 @@ Requires session authentication and instance ownership. Triggers a deploy of the POST /api/instance/:userId/stop ``` -Requires session authentication and instance ownership. Stops (suspends) the user's agent service on Railway. When managed runtime controls are disabled, this endpoint returns `503`. +Requires session authentication and instance ownership. Admin users bypass the ownership check and can stop any user's instance. Stops (suspends) the user's agent service on Railway. ### Path parameters @@ -196,9 +198,9 @@ Requires session authentication and instance ownership. Stops (suspends) the use | Code | Description | |------|-------------| | 401 | Unauthorized — no valid session | -| 403 | Forbidden — the authenticated user does not own the requested instance | +| 403 | Forbidden — the caller does not own the requested instance and is not an admin | | 500 | Failed to stop the service (for example, the Railway suspend mutation failed) | -| 503 | Managed runtime controls are disabled, or service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | +| 503 | Service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | --- @@ -208,7 +210,7 @@ Requires session authentication and instance ownership. Stops (suspends) the use POST /api/instance/:userId/restart ``` -Requires session authentication and instance ownership. Restarts the user's agent gateway on Railway. When managed runtime controls are disabled, this endpoint returns `503`. +Requires session authentication and instance ownership. Admin users bypass the ownership check and can restart any user's instance. Restarts the user's agent gateway on Railway. ### Path parameters @@ -230,9 +232,9 @@ Requires session authentication and instance ownership. Restarts the user's agen | Code | Description | |------|-------------| | 401 | Unauthorized — no valid session | -| 403 | Forbidden — the authenticated user does not own the requested instance | +| 403 | Forbidden — the caller does not own the requested instance and is not an admin | | 500 | Failed to restart the service (for example, the Railway restart mutation failed) | -| 503 | Managed runtime controls are disabled, or service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | +| 503 | Service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | --- @@ -242,7 +244,7 @@ Requires session authentication and instance ownership. Restarts the user's agen POST /api/instance/:userId/repair ``` -Requires session authentication and instance ownership. Performs a full reconfigure of the agent service: rewrites all environment variables on Railway and restarts the container. Use this to fix broken gateway tokens, corrupted configuration, or stuck containers. When managed runtime controls are disabled, this endpoint returns `503`. +Requires session authentication and instance ownership. Admin users bypass the ownership check and can repair any user's instance. Performs a full reconfigure of the agent service: rewrites all environment variables on Railway and restarts the container. Use this to fix broken gateway tokens, corrupted configuration, or stuck containers. The repair uses the user's per-user gateway token from the database. If no token exists, a new one is generated automatically. @@ -266,9 +268,9 @@ The repair uses the user's per-user gateway token from the database. If no token | Code | Description | |------|-------------| | 401 | Unauthorized — no valid session | -| 403 | Forbidden — the authenticated user does not own the requested instance | +| 403 | Forbidden — the caller does not own the requested instance and is not an admin | | 500 | Failed to repair the service (for example, the environment variable update or Railway restart mutation failed) | -| 503 | Managed runtime controls are disabled, or service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | +| 503 | Service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | --- @@ -278,7 +280,7 @@ The repair uses the user's per-user gateway token from the database. If no token POST /api/instance/:userId/reset-memory ``` -Requires session authentication and instance ownership. Wipes all stored agent memories from the database and restarts the container. The agent starts fresh as if newly provisioned. When managed runtime controls are disabled, this endpoint returns `503`. +Requires session authentication and instance ownership. Admin users bypass the ownership check and can reset any user's instance memory. Wipes all stored agent memories from the database and restarts the container. The agent starts fresh as if newly provisioned. This action permanently deletes all agent memory entries for the user. The workspace on Railway is ephemeral and resets on restart. @@ -302,9 +304,9 @@ Requires session authentication and instance ownership. Wipes all stored agent m | Code | Description | |------|-------------| | 401 | Unauthorized — no valid session | -| 403 | Forbidden — the authenticated user does not own the requested instance | +| 403 | Forbidden — the caller does not own the requested instance and is not an admin | | 500 | Failed to reset agent memory or restart the service | -| 503 | Managed runtime controls are disabled, or service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | +| 503 | Service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | --- @@ -314,7 +316,7 @@ Requires session authentication and instance ownership. Wipes all stored agent m POST /api/instance/:userId/update ``` -Requires session authentication and instance ownership. Updates the agent container to the platform's current default OpenClaw image and triggers a redeploy. When managed runtime controls are disabled, this endpoint returns `503`. +Requires session authentication and instance ownership. Admin users bypass the ownership check and can update any user's instance image. Updates the agent container to the platform's current default OpenClaw image and triggers a redeploy. ### Path parameters @@ -345,9 +347,9 @@ Requires session authentication and instance ownership. Updates the agent contai | Code | Description | |------|-------------| | 401 | Unauthorized — no valid session | -| 403 | Forbidden — the authenticated user does not own the requested instance | +| 403 | Forbidden — the caller does not own the requested instance and is not an admin | | 500 | Failed to update the service | -| 503 | Managed runtime controls are disabled, or service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | +| 503 | Service/config resolution failed. See [503 error details](#503-error-details) for the full list of causes. | --- @@ -357,7 +359,7 @@ Requires session authentication and instance ownership. Updates the agent contai GET /api/instance/:userId/token ``` -Requires session authentication and instance ownership. Returns the gateway token for the user's agent instance. +Requires session authentication and instance ownership. Admin users bypass the ownership check and can retrieve the gateway token for any user's instance. Returns the gateway token for the specified agent instance. ### Path parameters @@ -381,25 +383,16 @@ Requires session authentication and instance ownership. Returns the gateway toke | Code | Description | |------|-------------| -| 403 | Unauthorized — no valid session or the authenticated user does not own the requested instance | +| 403 | Unauthorized — no valid session or the caller does not own the requested instance and is not an admin | | 503 | No gateway token is configured on the platform | --- ## 503 error details -All lifecycle endpoints (start, stop, restart, repair, reset-memory, and update) return `503` in two scenarios: - -### Controls disabled +All lifecycle endpoints (start, stop, restart, repair, reset-memory, and update) return `503` when the platform cannot resolve the agent's service configuration. -When managed runtime controls are disabled via the `ENABLE_OPENCLAW_CONTROLS` or `NEXT_PUBLIC_ENABLE_OPENCLAW_CONTROLS` environment variables, all lifecycle endpoints return: - -```json -{ - "success": false, - "error": "Managed runtime controls are temporarily disabled until the Railway control path is fully verified." -} -``` +Managed runtime controls are always enabled. The `ENABLE_OPENCLAW_CONTROLS` and `NEXT_PUBLIC_ENABLE_OPENCLAW_CONTROLS` environment variables are no longer used to gate lifecycle actions — the controls flag is hardcoded to `true`. ### Service or configuration resolution failure @@ -495,7 +488,7 @@ POST /api/openclaw/maintenance Requires session authentication. Triggers a restart or factory reset of the user's agent container. The `action` field in the request body determines the behavior. -When managed runtime controls are disabled (via the `ENABLE_OPENCLAW_CONTROLS` or `NEXT_PUBLIC_ENABLE_OPENCLAW_CONTROLS` environment variables set to `false`), this endpoint returns `503` with the message: `Managed runtime controls are temporarily disabled until the Railway control path is fully verified.` +Managed runtime controls are always enabled. The controls flag is hardcoded to `true` and can no longer be disabled via environment variables. ### Request body @@ -589,7 +582,7 @@ When a restart or factory reset fails: | 401 | Unauthorized — missing or invalid session | | 404 | No agent deployed for the authenticated user | | 500 | Internal error during the restart or factory reset | -| 503 | Managed runtime controls are disabled, or the required Railway configuration (environment, project, or service) could not be resolved. When Railway configuration is the cause, the response body contains a descriptive error message. | +| 503 | The required Railway configuration (environment, project, or service) could not be resolved. The response body contains a descriptive error message. | Both `restart` and `factory-reset` cause a brief period of downtime while the container reinitializes. The `openclaw doctor --fix` process runs automatically during startup and may take additional time depending on the number of pending fixes or migrations.