# Scopes A scope is an opaque label (`[A-Za-z0-9._:-]{1,128}`, excluding `.` and `..`) that separates the connections and run history of different tenants, workspaces or environments inside one runtime. The runtime never interprets it. ## Model - A runtime token is created with an immutable `scope`: `POST /api/runtime-tokens` with `{ "scope": "tenant-a", ... }`. To change it, create a new token and revoke the old one. - A connection is stored with a scope: pass `scope` to `POST /v1/connections/:service/connect/api-key`, `/connect/custom-credential` or `/connect` (OAuth). The scope is fixed when the request starts and is stored with the pending OAuth state, so a callback cannot choose it. A reconnect keeps the scope of its target. - Every lookup is confined to the caller's scope in the store itself: a scoped token reads only connections of its scope, and every request without a scoped token (an unscoped token, the static `runtimeToken`, JWT credentials, the administrator on `/v1/actions`) reads only unscoped connections. Existing single-tenant installs, whose connections are all unscoped, behave as before. For runtime lookup and execution, a caller never sends a scope — it always comes from authentication. Only `/v1` connection-start endpoints accept `scope` (from the administrator, or optionally an `allowConnect` token's own scope; any other scope is rejected). - Another scope's connection is never read, so it answers exactly like a connection that does not exist, whether it is selected by alias or by id, listed, searched or offered as a default. - An empty `allowedConnections` list never widens a token beyond its scope. - Connection names generated by `/v1` are random. A name that already belongs to another scope is rejected (`connection_scope_conflict`) inside the same write, so concurrent requests cannot take a name over; only the administrator chooses names. Replacing a connection from the console keeps its scope. ## Tenant connect tokens By default only the administrator token can start or read connections. A scoped token created with `"allowConnect": true` (it requires a `scope`) may also use this subset of `/v1`, confined to its own scope: - `POST /v1/connections/:service/connect`, `/connect/api-key`, `/connect/custom-credential` and the `/v1/connections/by-id/:appId/connect...` reconnect variants. The scope comes from the token; a body that names another scope is rejected with `invalid_input`. An OAuth start may choose `authorizationOptionIds`, but `returnUri`, `extra` and `secretExtra` stay administrator-only: they would let a tenant redirect users anywhere or point the token exchange, with the client secret, at its own host. A tenant polls the connection request instead. - `GET /v1/connections`, `GET /v1/connections/by-id/:appId`, `GET /v1/connection-requests/:id` and `GET /v1/providers/:service/setup`. A connection or request of another scope answers `404`, the same as one that does not exist. Pending OAuth requests are owned per scope, so one tenant starting a provider never supersedes another tenant's pending request and cannot poll it. The administrator (bearer or console session) can poll every request. Everything else stays administrator-only, including disconnecting, OAuth client configuration, runtime tokens, `/api/*` and SaaS-hosted authorization (a scoped start for a service that uses a SaaS source is refused rather than stored unscoped). A token without `allowConnect`, an unscoped token and the static `runtimeToken` still receive `401` on these paths. A host can therefore keep the administrator token to itself, mint one `allowConnect` token per tenant and let the tenant's own backend start connections and poll them directly. ## Run history Runs record the scope of the token that made them. `GET /api/runs?scope=...` lists one scope and `DELETE /api/runs?scope=...` deletes it, so a tenant's history can be removed on offboarding independently of the count-based `runLimit`. ## Transit files Files that an action creates carry the scope of the token that ran it, on all four backends (local disk, S3, R2, KV), and the executor can read back only files of that scope. A runtime token that has no scope sees only unscoped files. `POST /api/files?scope=...` (admin) uploads a file into a scope. `GET /api/files/:id` stays open for files that belong to no scope. A scoped file is served only to a bearer of the same scope or to the admin token, and to anyone else it is `404 file_not_found`, the same answer as a missing file. A host that hands a scoped `downloadUrl` to a browser must therefore proxy the download with the scoped token. `DELETE /api/files/:id` follows the same rule. ## Deleting a scope `DELETE /api/scopes/:scope` (admin) revokes the scope's runtime tokens, fails its open OAuth requests, including console reconnects of its connections (a callback already in flight cannot store its connection; the grant it obtained is revoked on a best-effort basis, and a failed provider revocation is logged rather than reported), cancels its trigger subscriptions, disconnects its stored connections (revoking OAuth grants, including connections whose provider has left the catalog), purges its runs and deletes its transit files. It answers `200` with the counts, or `207` with a `failures` list when a step failed; call it again to finish. Nothing outside the scope is touched. ## Not covered yet - Connection names are unique per service across scopes rather than per scope. - Proxy calls are not recorded as runs, and runs carry no trace id. - Deleting a scope leaves its idempotency records, which expire on their own. - Deleting a scope does not clean up `resource-set` trigger subscriptions or `trigger_source_applications` records. - The console is an operator view and is not filtered by scope. - Deleting a scope does not wait for requests already running with a revoked token: a run or file an action writes after the purge, or a connection request a start inserts after the cancel, stays until the next call (or the file TTL). Call the endpoint again once they have finished. Closing this fully needs a durable record of deleted scopes. - A scoped token cannot subscribe to triggers of a provider used without a connection (`no_auth`): such a subscription would belong to no scope, so it could be neither confined nor removed with the scope.