/v1/scopes
Register, inspect, and manage hierarchical scopes and their members.
Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Response Body
curl -X GET "https://example.com/v1/scopes/list"Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Query Parameters
Response Body
curl -X PUT "https://example.com/v1/scopes/members?path=string"The full scope surface
| Route | Result |
|---|---|
POST /v1/scopes | 201 register a scope (duplicate → 409 SCOPE_REGISTRATION_EXISTS). |
GET /v1/scopes?path= | { path, billing_tenant, members, policies, auto_provisioned, created_at }. billing_tenant is server-derived and read-only ("default" on a single-tenant self-host; supplying it on registration is not allowed). Present on v0.9.13, not in the v0.9.9 schema. |
GET /v1/scopes/list?prefix= | { items: [...] } — each item is the full record, not a minimal subset. |
PUT /v1/scopes/members?path= | Replaces the member list (200). |
POST /v1/scopes/prune { older_than, dry_run } | { candidates: [...] }. |
DELETE /v1/scopes?path= | Detaches the scope registration (see below). |
Behavior notes
Ownership
The caller is auto-added as an owner member on create. Delete is owner-gated — after a
PUT members that drops your actor, DELETE → 403 POLICY_DENIED "owner role required to delete a scope". The operator key and no-auth mode are not bound by membership (their DELETE returns 204),
so control who holds the operator key rather than relying on membership.
Scope policies
A scope's policies is the server's own { children: { auto_register: true } }; keys such as
retention, default_view or diagnostics_allowed sent on create are not stored, and there is no
inherited_policy. Set retention with the retention routes.
See Scopes for the hierarchy model and view semantics.