Scope Sets
Named bundles of scopes that can be attached to users, groups, or API keys. Scope sets let you define a "role" once and reuse it — instead of editing each user's scope list individually when permissions change, you edit the scope set.
Scopes
| Scope | Reach |
|---|---|
scope_sets:read | Listing, reading, viewing filters. |
scope_sets:write | Creating, modifying, deleting scope sets. |
Endpoints
List Scope Sets
GET /api/admin/scope-sets/
Returns a page of scope-set records.
Required scope: scope_sets:read · also accepts API key
Query parameters — standard pagination set; see Conventions › Pagination. Defaults: sort_by=created, sort_order=desc, hydrate=true.
Response 200 — ScopeSetInDbCursorPage
Get Scope Set Filter Metadata
GET /api/admin/scope-sets/filters
Returns filter/operator/sort options for List Scope Sets.
Required scope: scope_sets:read
Response 200 — open metadata object.
Get Scope Set by ID
GET /api/admin/scope-sets/{id}
Returns a single scope-set record, including the scopes it bundles.
Required scope: scope_sets:read · also accepts API key
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Scope set ID. |
Response 200 — ScopeSetRead
Create Scope Set
POST /api/admin/scope-sets/
Creates a new scope set.
Required scope: scope_sets:write
Request body — ScopeSetWriteCreate
Response 201 — ScopeSetRead
Update Scope Set by ID
PUT /api/admin/scope-sets/{id}
Replaces the scope set.
Required scope: scope_sets:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Scope set ID. |
Request body — ScopeSetWriteReplace
Response 200 — ScopeSetRead
Patch Scope Set
PATCH /api/admin/scope-sets/{id}
Partial scope-set update.
Required scope: scope_sets:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Scope set ID. |
Request body — ScopeSetWriteUpdate
Response 200 — ScopeSetRead
Delete Scope Set by ID
DELETE /api/admin/scope-sets/{id}
Removes a scope set. Users, groups, and API keys that referenced this scope set lose those scopes.
Required scope: scope_sets:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Scope set ID. |
Response 204 — empty.
WARNING
Deleting a scope set immediately revokes its scopes from every principal that referenced it. Inspect referencing users/groups/keys first to avoid unintended access loss.