Create Scope

Create a custom tenant-scoped permission scope for fine-grained agent access control

Create Scope

POST /v1/scopes

Creates a custom permission scope for the authenticated tenant. Custom scopes extend the built-in scope registry with tenant-specific permissions. The scope string is automatically composed from the resource and action fields in resource:action format.

Custom scopes are validated against the MAIP scope format rules: alphanumeric characters, dots, underscores, hyphens, and asterisks only.

Custom scopes are tenant-isolated. They do not appear in other tenants’ scope registries. Built-in platform scopes cannot be overridden or duplicated.

Authentication

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

Request Body

resource · string · required

The resource component of the scope. Must contain only alphanumeric characters, dots, underscores, and hyphens. Examples: "crm", "payment", "inventory.warehouse".

action · string · required

The action component of the scope. Must contain only alphanumeric characters, dots, underscores, hyphens, and asterisks. Examples: "read", "approve", "*".

display_name · string

Human-readable name for the scope. Defaults to the composed resource:action string if omitted.

description · string

Detailed description of what the scope grants access to.

category · string

Organizational category for the scope. Defaults to "custom" if omitted. Common values: "data", "model", "tool", "integration", "custom".

Response

id · string

UUID of the newly created scope definition.

tenant_id · string

UUID of the owning tenant.

scope · string

The composed scope string in resource:action format.

resource · string

The resource component.

action · string

The action component.

display_name · string

Human-readable scope name.

description · string

Scope description.

category · string

Scope category.

is_builtin · boolean

Always false for tenant-created scopes.

created_at · string

ISO 8601 creation timestamp.

Example

curl -X POST https://api.truthlocks.com/v1/scopes \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "crm",
    "action": "contact.enrich",
    "display_name": "CRM Contact Enrichment",
    "description": "Allows agents to enrich CRM contact records via third-party providers",
    "category": "integration"
  }'

---

Assigning Custom Scopes to Agents

After creating a custom scope, assign it to agents during registration or via delegation:

curl -X POST https://api.truthlocks.com/v1/agents \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "pipeline",
    "display_name": "CRM Enrichment Pipeline",
    "scopes": ["crm:contact.enrich", "data:read"]
  }'