Skip to main content
GET
/
v1
/
agents
/
{agentId}
/
scopes
List Agent Scopes
curl --request GET \
  --url https://api.truthlocks.com/v1/agents/{agentId}/scopes \
  --header 'X-API-Key: <api-key>'
{
  "scopes": [
    "<string>"
  ]
}

​
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:
CategoryScopesDescription
dataread, write, delete, *Data resource access
modeltrain, evaluate, deploy, attest, *ML model lifecycle
toolsearch.web, search.db, execute, *Tool invocation
agentdelegate, manage, inspect, *Agent lifecycle management
adminconfig, audit, billing, *Administrative operations
receiptcreate, 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")

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Path Parameters

​
agentId
string<uuid>
required

Agent identifier

Response

Agent scopes

​
scopes
string[]