> ## 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.

# Crear alcance

> Cree un alcance de permiso personalizado a nivel de inquilino para un control de acceso de agente granular

# Crear Ámbito

`POST /v1/scopes`

Crea un ámbito de permiso personalizado para el inquilino autenticado. Los ámbitos personalizados extienden el registro de ámbitos incorporado con permisos específicos del inquilino. La cadena de ámbito se compone automáticamente a partir de los campos `resource` y `action` en formato `resource:action`.

Los alcances personalizados se validan según las reglas de formato de alcance MAIP: solo caracteres alfanuméricos, puntos, guiones bajos, guiones y asteriscos.

> [!NOTE]
>
> Los ámbitos personalizados están aislados por inquilino. No aparecen en los ámbitos de otros inquilinos.
> registros. Los ámbitos de plataforma incorporados no se pueden anular ni duplicar.

### Autenticación

Requiere el encabezado `X-API-Key` o el token Bearer JWT. El espacio de trabajo se deriva de la credencial autenticada; no envíe `X-Tenant-ID`.

### Respuesta

**id** `string`

UUID de la definición de ámbito recién creada.

**tenant\_id** `string`

UUID del inquilino propietario.

**scope** `string`

La cadena de alcance compuesta en formato `resource:action`.

**resource** `string`

El componente de recurso.

**action** `string`

El componente de acción.

**display\_name** `string`

Nombre del ámbito legible por humanos.

**description** `string`

Descripción del alcance.

**category** `string`

Categoría de alcance.

**is\_builtin** `boolean`

Siempre `false` para ámbitos creados por el inquilino.

**created\_at** `string`

Marca de tiempo de creación ISO 8601.

### Ejemplo

```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"
  }'
```

***

### Asignación de ámbitos personalizados a agentes

Después de crear un alcance personalizado, asígnelo a los agentes durante el [registro](https://docs.truthlocks.com/es/api-reference/machine-identity/agents/register.md) o mediante [delegación](https://docs.truthlocks.com/es/api-reference/machine-identity/agents/register.md):

```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 es/mint-openapi.yaml POST /v1/scopes
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks es una infraestructura de verificación universal para documentos,
    credenciales y activos digitales.

    Esta especificación define la API canónica para interactuar con los
    servicios de Truthlocks.


    ## URLs Base

    - **Producción**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Autenticación

    - **Claves API**: Use el encabezado `X-API-Key` para operaciones máquina a
    máquina

    - **Tokens Bearer**: Use `Authorization: Bearer <jwt>` para operaciones
    iniciadas por el usuario


    ## Identidad del Inquilino

    En producción, la identidad del inquilino se deriva del contexto autenticado
    (clave API o JWT).

    El encabezado `X-Tenant-ID` se ignora en producción para evitar la
    suplantación de identidad.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: API de producción
  - url: https://sandbox-api.truthlocks.com
    description: Entorno Sandbox
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: Gestión de claves y tokens de API
  - name: Issuers
    description: Registro del emisor y gestión de la confianza
  - name: Keys
    description: Gestión de claves criptográficas para emisores
  - name: Attestations
    description: Ciclo de vida de la atestación (acuñar, revocar, reemplazar)
  - name: Verification
    description: Verificación de atestación y paquetes de prueba
  - name: Governance
    description: Flujos de trabajo de gobernanza del emisor (solo administrador)
  - name: Identity
    description: Gestión de organización, usuarios y roles
  - name: Audit
    description: Consultas de eventos de auditoría
  - name: Tenant Console
    description: Puntos finales de perfil y ciclo de vida del inquilino
  - name: Health
    description: Endpoints de estado y preparación del servicio
  - name: Risk
    description: Ingesta de señales de riesgo y detección de fraude
  - name: Risk Enforcement
    description: >-
      Acciones de aplicación de riesgos: bloqueo, desafío, cuarentena y
      configuración
  - name: Billing
    description: Gestión de facturación, suscripciones y complementos
  - name: Machine Identity
    description: >-
      Protocolo de Identidad de Agente de Máquina (MAIP) — registro de agentes,
      sesiones, confianza, testigo, cumplimiento, orquestación y observabilidad
externalDocs:
  description: API de transparencia de solo lectura (especificación de servicio separada)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/scopes:
    post:
      tags:
        - Machine Identity
      summary: Crear alcance
      description: >-
        Crea un ámbito de permiso personalizado con alcance de inquilino para un
        control de acceso de agente granular.
      operationId: maip.scopes.create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                action:
                  type: string
                  description: >-
                    Componente de acción del alcance (por ejemplo, "leer",
                    "aprobar", "*")
                category:
                  type: string
                  description: Categoría organizacional (por defecto "custom")
                description:
                  type: string
                  description: Descripción detallada de lo que otorga el ámbito
                display_name:
                  type: string
                  description: Nombre legible por humanos para el alcance
                resource:
                  type: string
                  description: >-
                    Componente de recurso del alcance (por ejemplo, "crm",
                    "payment")
              type: object
              required:
                - resource
                - action
      responses:
        '201':
          description: Alcance creado
          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: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Autenticación requerida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: El alcance ya existe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Límite de velocidad excedido
          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: Código de error legible por máquina
          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: Mensaje de error legible por humanos
        http_status:
          type: integer
          description: Código de estado HTTP
        retry_after_ms:
          type: integer
          description: Milisegundos a esperar antes de reintentar (para límites de tasa)
        details:
          type: object
          description: Contexto de error adicional
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Clave API para autenticación máquina a máquina
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT para operaciones iniciadas por el usuario

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.