> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
The resource component of the scope. Must contain only alphanumeric
characters, dots, underscores, and hyphens. Examples: `"crm"`, `"payment"`,
`"inventory.warehouse"`.
The action component of the scope. Must contain only alphanumeric characters,
dots, underscores, hyphens, and asterisks. Examples: `"read"`, `"approve"`,
`"*"`.
Human-readable name for the scope. Defaults to the composed `resource:action`
string if omitted.
Detailed description of what the scope grants access to.
Organizational category for the scope. Defaults to `"custom"` if omitted.
Common values: `"data"`, `"model"`, `"tool"`, `"integration"`, `"custom"`.
### Response
UUID of the newly created scope definition.
UUID of the owning tenant.
The composed scope string in `resource:action` format.
The resource component.
The action component.
Human-readable scope name.
Scope description.
Scope category.
Always `false` for tenant-created scopes.
ISO 8601 creation timestamp.
### Example
```bash theme={null}
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](/api-reference/machine-identity/agents/register) or via [delegation](/api-reference/machine-identity/agents/register):
```bash theme={null}
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"]
}'
```
## OpenAPI
````yaml mint-openapi.yaml POST /v1/scopes
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/scopes:
post:
tags:
- Machine Identity
summary: Create Scope
description: >-
Creates a custom tenant-scoped permission scope for fine-grained agent
access control.
operationId: maip.scopes.create
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- resource
- action
properties:
resource:
type: string
description: Resource component of the scope (e.g. "crm", "payment")
action:
type: string
description: Action component of the scope (e.g. "read", "approve", "*")
display_name:
type: string
description: Human-readable name for the scope
description:
type: string
description: Detailed description of what the scope grants
category:
type: string
description: Organizational category (defaults to "custom")
example:
resource: crm
action: contact.enrich
display_name: CRM Contact Enrichment
description: Allows agents to enrich CRM contact records
category: integration
responses:
'201':
description: Scope created
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
tenant_id:
type: string
format: uuid
scope:
type: string
resource:
type: string
action:
type: string
display_name:
type: string
description:
type: string
category:
type: string
is_builtin:
type: boolean
created_at:
type: string
format: date-time
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: Scope already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- APIKey: []
components:
schemas:
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````