> ## 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.
# 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
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.
UUID of the scope definition.
UUID of the tenant that owns this scope. `null` for platform-level built-in
scopes.
The full scope string in `resource:action` format (e.g., `"data:read"`,
`"model:train"`).
The resource component of the scope (e.g., `"data"`, `"model"`, `"tool"`).
The action component of the scope (e.g., `"read"`, `"write"`, `"*"`).
Human-readable name for the scope.
Detailed description of what the scope grants access to.
Scope category for organizational purposes.
`true` for platform-defined scopes, `false` for tenant-created custom scopes.
ISO 8601 creation timestamp.
### Example
```bash theme={null}
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")
```
## OpenAPI
````yaml mint-openapi.yaml GET /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:
get:
tags:
- Machine Identity
summary: List Scopes
description: >-
Returns all permission scopes available to the authenticated tenant,
including platform built-ins and tenant custom scopes.
operationId: maip.scopes.list
parameters:
- name: category
in: query
required: false
schema:
type: string
enum:
- data
- model
- tool
- agent
- admin
- receipt
- custom
description: Filter scopes by category
responses:
'200':
description: Available scopes
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
tenant_id:
type: string
format: uuid
nullable: true
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
'401':
description: Authentication required
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
````