๐ก๏ธ Permissions and Rate Limits¶
Control who can reach your API server and what they can run under api:permissions (mrsm edit config api):
- Route groups โ turn entire surfaces on or off (
--public,allowlist,disabled). - Roles & scopes โ control per-user and per-token permissions (Tokens).
- Rate & size limits โ throttle abusive clients and cap request payloads.
Route groups¶
Disabled core groups return 404 and are never proxied to plugins:
# mrsm edit config api
api:
permissions:
routes:
allowlist: ['*'] # Glob patterns to serve (omit for all)
disabled: ['actions'] # Always disabled (including `login`)
| Group | Routes |
|---|---|
pipes |
/pipes/*, /metadata |
pipelines |
/pipelines, /pipelines/* |
engine |
/engine/* |
actions |
/actions/*, /execute* |
jobs |
/jobs/*, /logs/* |
connectors |
/connectors |
users, tokens, plugins |
/users/*, /teams/*, /tokens/*, /plugins/* |
version |
/version, /version/mrsm |
misc |
/healthcheck, /info, /chaining, /favicon.ico |
index |
/ (redirect) |
mcp |
/mcp (MCP server) |
dash |
Web console pages |
/login stays enabled unless explicitly disabled; /docs, /redoc, /openapi.json, the web terminal, and plugin routes live outside core groups.
The public preset¶
To expose only your plugin routes and public web pages (such as a public dashboard), start with --public or set preset: public:
public serves only /login, /healthcheck, /version, @api_plugin routes, plugin pages, and their static assetsโturning off the console, web terminal, /actions, /execute, registration, and API docs.
Roles and teams¶
The first account created on an empty instance becomes an administrator. After that, self-registration is off by default (api:permissions:registration:users: false), and new users join Everyone with api:permissions:default_role (editor).
| Role | Permissions |
|---|---|
| Viewer | Read visible pipes, Pipelines, runs, jobs, logs, plugins, and connectors list; manage own account and tokens. |
| Editor | Viewer, plus register, define, edit, and sync pipes, read SQL, and start existing jobs. |
| Operator | Editor, plus execute actions, use the web terminal, and create, stop, pause, or delete jobs. |
| Admin | Full access, including users, teams, and connector details (type: admin). |
- Custom scopes: Explicit permission lists replace the role. Token scopes always intersect with the owner's current permissions, so demoting a user immediately narrows their tokens.
- Teams & locks: Every user belongs to Everyone. See Pipe access and locks for visibility and locks, and Teams on One Instance for isolated databases and sandboxes.
- Connector isolation: Add
teams: [Data, Operations]to a connector to restrict API access; use least-privilege DB users when strict SQL isolation is required.
Who may run actions¶
Running remote actions needs actions:execute and opening the web terminal needs webterm:use (Operator or Admin). Clicking Sync or Verify on a pipe only needs pipes:write and edit access on that pipe.
Non-administrators can only run approved Meerschaum actions through /execute, /jobs, /actions, console Exec, MCP execute_action, and the web terminalโnever raw shell commands (sh, os, python, !command), editors, or SQL clients.
- Lock all remote actions and terminals to admins with
mrsm start api --secure(api:permissions:actions:non_admin: false). - Isolated teams with
plugins_writerun sandboxed team commands and terminals; eligible teams withoutplugins_writecan run API-only commands.
Allowed non-administrator commands¶
Every command below is scoped to objects the caller can read or edit with matching API permissions:
| Action | Subactions |
|---|---|
help |
(none) |
show |
version, help, actions, arguments, schedules, pipes, data, columns, rowcounts, sizes, partitions, targets, tags, pipelines, jobs, daemons, tokens |
sync |
pipes, pipelines |
verify |
pipes, rowcounts, schemas |
deduplicate |
pipes |
clear |
pipes, pipelines |
drop |
pipes, pipelines |
delete |
pipes, pipelines, jobs |
lock |
pipes |
unlock |
pipes |
edit |
pipes |
partition |
pipes |
tag |
pipes |
attach |
jobs, logs |
watch |
jobs, logs |
stop |
jobs, daemons |
pause |
jobs |
restart |
jobs, daemons |
Non-administrators cannot redirect commands to another executor or run show connectors. Scoped API keys keep these limits even when owned by an admin.
Permissions fail closed¶
If reading permissions, teams, or credentials fails, the server returns 503 rather than falling back to defaults. Identities cache up to 5 seconds and pipe access up to 3 seconds, and both invalidate immediately on writes.
Rate limits¶
Configure per-client token buckets under api:permissions:rate_limits (requests per seconds, or max per window_seconds):
# mrsm edit config api
api:
permissions:
rate_limits:
login: {requests: 10, seconds: 60}
pipes: {max: 1000, window_seconds: 60}
/my-plugin: {requests: 30, seconds: 60}
'*': {requests: 600, seconds: 60}
Keys match route groups (login, docs, mcp, webterm, other), globs, or /prefix paths (longest prefix wins). Throttled callers receive 429 with Retry-After. Behind a reverse proxy, set api:server:forwarded_allow_ips and api:server:proxy_headers so limits track the real client IP.
Request size limits¶
Oversized payloads are rejected with 413 before buffering (set any limit to null to disable):
# mrsm edit config api
api:
limits:
auth_bytes: 65536 # /login, /users/register, /tokens/* (64 KiB)
body_bytes: 16777216 # JSON/form, /execute, MCP (16 MiB)
data_bytes: 1073741824 # Pipe data sync (1 GiB)
proxy_bytes: 16777216 # Requests proxied to Python API host (16 MiB)
host:
response_seconds: 300 # Timeout waiting for host response start (504)
Responses, SSE streams, and WebSockets are unlimited; engine routes (64 MiB) and plugin uploads (128 MiB) keep their own caps.