Skip to content

Document admin access on instance routes #404

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document admin access on instance routes #404

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3a074b1
Document admin bypass on instance routes and always-enabled runtime c…
mintlify[bot] Apr 12, 2026
3faedb5
Merge branch 'main' into mintlify/admin-instance-access-1776000845
Eskyee Apr 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 21 additions & 28 deletions api-reference/agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: "Create, manage, and interact with agents"

Create, manage, and interact with agents.

<Note>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.</Note>
<Note>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.</Note>

## List agents

Expand Down Expand Up @@ -195,7 +195,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 |

Expand Down Expand Up @@ -955,8 +955,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.

Expand Down Expand Up @@ -993,10 +993,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

Expand Down Expand Up @@ -1029,10 +1029,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

Expand Down Expand Up @@ -1072,10 +1072,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

Expand Down Expand Up @@ -1134,10 +1134,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

Expand Down Expand Up @@ -1172,10 +1172,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

Expand Down Expand Up @@ -1206,10 +1206,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

Expand Down Expand Up @@ -1239,16 +1239,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
{
Expand All @@ -1257,14 +1248,16 @@ When service or configuration resolution fails, the error message describes the
}
```

<Note>Managed runtime controls are always enabled. The controls flag is hardcoded to `true` and can no longer be disabled via environment variables.</Note>

| 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

Expand Down
47 changes: 19 additions & 28 deletions api-reference/maintenance.mdx
View file
Open in desktop
Copy link
Copy Markdown

@devin-ai-integration devin-ai-integration Bot Apr 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Incomplete transformation: maintenance endpoint still references disabled controls that are now hardcoded to true

Line 546 of api-reference/maintenance.mdx still says "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..." — but the rest of this PR explicitly removes all such references and states that controls are always enabled (e.g., api-reference/maintenance.mdx:422 says "Managed runtime controls are always enabled... the controls flag is hardcoded to true"). This contradicts the PR's own changes and will confuse readers about whether controls can be disabled.

(Refers to line 546)

Prompt for agents 
In api-reference/maintenance.mdx, line 546 still contains the old text: '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.' This contradicts the rest of the PR which removes all references to controls being disabled and adds notes that controls are always enabled (hardcoded to true). This paragraph should either be removed entirely or rewritten to say that controls are always enabled, consistent with the note at line 422 of the same file and line 1251 of api-reference/agents.mdx.
Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,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.` |

---

Expand Down Expand Up @@ -159,7 +159,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 |

---

Expand Down Expand Up @@ -191,9 +191,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. |

---

Expand Down Expand Up @@ -225,9 +225,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. |

---

Expand Down Expand Up @@ -259,9 +259,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. |

---

Expand Down Expand Up @@ -295,9 +295,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. |

---

Expand Down Expand Up @@ -331,9 +331,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. |

---

Expand Down Expand Up @@ -374,9 +374,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. |

---

Expand All @@ -386,7 +386,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

Expand All @@ -410,25 +410,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:
All lifecycle endpoints (start, stop, restart, repair, reset-memory, and update) return `503` when the platform cannot resolve the agent's service configuration.

### Controls disabled

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."
}
```
<Note>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`.</Note>

### Service or configuration resolution failure

Expand Down Expand Up @@ -646,7 +637,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. |

<Warning>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.</Warning>

Expand Down