Gates
A gate is a named HTTP endpoint that forwards requests to one fixed target (an HTTP URL or a plugin function) behind the platform's authentication and an optional per-gate access rule. Gates are how you expose one specific thing (a plugin function, an internal service) to some set of callers without handing out broad API keys.
Gates are global (they live in the default database) and are managed as
records; calling one is a single stable URL.
Quick start
# once, as admin: expose a plugin function through a gate
curl -X POST "$VSKI_URL/api/collections/_gates/records" \
-H "X-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{
"name": "tagger-invoke",
"url": "plugin://tagger/on_photo",
"rules": "*"
}'
# any authenticated caller the rule allows can now call it; the body is
# the function's params:
curl -X POST "$VSKI_URL/api/gates/tagger-invoke" \
-H "X-API-Key: $VIEWER_KEY" -H "Content-Type: application/json" \
-d '{"id": "1", "image": "a.jpg"}'
The SDKs wrap the call side:
result = client.gate("tagger-invoke", {"id": "1", "image": "a.jpg"})
and in TypeScript:
const result = await client.gate("tagger-invoke", { id: "1", image: "a.jpg" });
Managing gates
Gates are records of the _gates system collection (admin only; the
system collection has empty default rules, which deny non-admins). The
web console has a dedicated page under Settings → API Gates.
| field | meaning |
|---|---|
name |
unique; used in the route /api/gates/{name} |
url |
the fixed target: an http(s):// URL, or plugin://<instance>/<function> |
rules |
access rule: null/"*" = any authenticated caller, "" = admins only, or a rule expression |
headers |
JSON-encoded string map of headers set on proxied HTTP requests (incoming values are overridden) |
method |
documentation only: the caller's HTTP method is always forwarded, this field does not restrict it |
description |
free text |
# list / update / delete like any collection record
curl "$VSKI_URL/api/collections/_gates/records" -H "X-API-Key: $ADMIN_KEY"
curl -X PATCH "$VSKI_URL/api/collections/_gates/records/<id>" \
-H "X-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
-d "{\"rules\": \"'editors' in @request.auth.roles\"}"
Calling a gate
Routes: GET/POST/PUT/DELETE/PATCH /api/gates/{name}, behind the global
auth middleware: every caller must present an API key or a token
(anonymous requests get 401 before the gate is even looked up).
The gate's rule is then evaluated with the caller's identity, e.g.
@request.auth.id = 'u_123' or 'editors' in @request.auth.roles, the
same expression syntax as collection rules (see
Rules and Access Control); admins bypass
rules. Request data is not available to gate rules. A denied caller gets
403.
Everything else depends on the target type.
HTTP targets (http:// / https://)
The gate acts as a reverse proxy:
- The caller's method and raw body are forwarded verbatim to the fixed URL. Query parameters are not forwarded; anything the target needs must be baked into the gate's URL.
- Incoming headers are copied (minus
host/connection/content-length/transfer-encoding), then the gate'sheadersmap is applied on top. This is how a gate injects a credential an upstream service expects without callers ever seeing it. - The upstream's status code and headers are passed through; the body is
fully buffered and returned with
Content-Type: application/json. - There is no timeout and no retry: a slow upstream holds the caller connection open indefinitely. There is also no streaming: a gate cannot carry SSE or chunked responses.
- Per-gate call statistics are recorded under the stats collection
gate:<name>.
Plugin targets (plugin://<instance>/<function>)
A plugin target dispatches the call over the warm plugin pipe: no HTTP hop, no credentials to inject:
- The caller's JSON body becomes the function's params (it must be a JSON object; an empty body is an empty object).
- The function's return value comes back verbatim as the response body.
- The function identity is fixed by the gate record: callers pick the payload, never the function. This is the important security property: a caller you allow through the rule can do exactly one thing.
- The instance must be running (
502otherwise, with the reason). - The call rides the standard plugin invoke budget (30 s default, 120 s hard cap). Work longer than that belongs in a pipeline, not a gate.
- The database the instance is looked up in comes from the caller's
x-dbnameheader (defaultdefault).
Prefer
plugin://targets over the HTTP bridge. Pointing a gate at the server's ownPOST /api/plugin-instances/{name}/invokeroute with an injected admin key also works, but there the caller's body selects the function; anyone passing the rule can invoke any function on that instance with admin authority.plugin://targets exist to close exactly that hole. (The bridge remains useful for servers that predate plugin targets.)
Security notes
- Only admins can create, list, update or delete gates.
rulesis the only per-gate access control; there are no per-gate rate limits or quotas. A gate namedrules: "*"is reachable by every authenticated principal; use a rule expression to narrow it.- An HTTP gate's
urlis arbitrary: admins can point it at internal services (that is the feature), so treat gate-creation rights as sensitive as the credentials a gate can inject. - Gates buffer whole request and response bodies; do not route large payloads through them.
Stats
Every gate call records a hit under gate:<name> (status and duration),
visible in the SQL console / stats views like any _stats_* collection.
See also
- Plugins: plugin instances and functions
- Rules and Access Control: rule syntax
- Webhooks: outbound event delivery, including
plugin://targets from triggers
- Introduction
- Performance
- Getting Started
- Coding Agents
- Command Line
- Infra as Code
- CI/CD Guide
- Project Boilerplate
- SDKs
- Authentication
- Databases
- Collections
- Gated Queries
- Graphs
- Rules and Access Control
- Granular Access Control
- Triggers
- Plugins
- Containers Plugin
- vski mcp
- Realtime
- Full Text Search
- Vector Embeddings
- KWH
- Workflows
- Pipelines
- Dashboard Widgets
- Connectors
- Cron
- Webhooks
- Gates
- Migrations
- Replication
- File Sync
- Backup
- Distributed Realtime
- Tutorial: ReactJS Todo
- Tutorial: Graph-Memory Agent
- Tutorial: Image Gallery
- Tutorial: Embeddings
- Tutorial: Graphs
- Recipe: Calendar Timetree
- Tutorial: Plugins
- Tutorial: MCP Server