List Scopes

List all available permission scopes including platform built-ins and tenant custom scopes

List Scopes

GET /v1/scopes

Returns all permission scopes available to the authenticated tenant. This includes platform-defined built-in scopes and any custom scopes created by the tenant. Scopes follow the resource:action format defined by the MAIP protocol.

Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

Query Parameters

category · string

Filter scopes by category. One of: "data", "model", "tool", "agent", "admin", "receipt", "custom". Omit to return all categories.

Response

Returns an array of scope definition objects.

id · string

UUID of the scope definition.

tenant_id · string

UUID of the tenant that owns this scope. null for platform-level built-in scopes.

scope · string

The full scope string in resource:action format (e.g., "data:read", "model:train").

resource · string

The resource component of the scope (e.g., "data", "model", "tool").

action · string

The action component of the scope (e.g., "read", "write", "*").

display_name · string

Human-readable name for the scope.

description · string

Detailed description of what the scope grants access to.

category · string

Scope category for organizational purposes.

is_builtin · boolean

true for platform-defined scopes, false for tenant-created custom scopes.

created_at · string

ISO 8601 creation timestamp.

Example

curl -G https://api.truthlocks.com/v1/scopes \
  -H "X-API-Key: tl_live_..." \
  -d "category=data"

---

Built-in Scope Categories

The platform provides 25+ built-in scopes across 6 categories:

Category	Scopes	Description
data	read, write, delete, *	Data resource access
model	train, evaluate, deploy, attest, *	ML model lifecycle
tool	search.web, search.db, execute, *	Tool invocation
agent	delegate, manage, inspect, *	Agent lifecycle management
admin	config, audit, billing, *	Administrative operations
receipt	create, verify, revoke, *	Receipt management

Scope Format Reference

resource:action         Standard scope (e.g., "data:read")
resource:*              Wildcard scope (e.g., "data:*" grants all data actions)
!resource:action        Negation scope (e.g., "!data:delete" explicitly denies)
resource:sub.action     Dotted sub-actions (e.g., "tool:search.web")