/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, members, policies, auto_provisioned, created_at }. |
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 (v0.9.9)
DELETE detaches and keeps records — no SCOPE_HAS_RECORDS 409
Deleting a scope that still has records, with the records param omitted, returns 204 — it
detaches the registration (a subsequent GET /v1/scopes?path= → 404 "scope not registered") and
leaves the events intact. The v1 docs' "reject with 409 SCOPE_HAS_RECORDS" guard does not
fire; the default silently behaves like records=keep. (Append-only-safe — events are retained — but
the promised safety reject is missing.)
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".
Documented policy keys are not stored/echoed
Creating with policies: { retention, default_view, diagnostics_allowed } does not persist or echo
those keys — the response policies comes back as { children: { auto_register: false } }, and
inherited_policy is not returned. Don't rely on scope-level policy keys round-tripping on
v0.9.9.
See Scopes for the hierarchy model and view semantics.