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

# RBAC y permisos

> Control de acceso basado en roles y gestión de permisos.

Truthlocks implementa el control de acceso basado en roles (RBAC) para gestionar quién puede realizar qué acciones. Esta guía explica el modelo de permisos.

## Modelo de permisos

El modelo de permisos de Truthlocks consta de tres capas:

**1. Permisos**

Acciones atómicas como `attestations:mint` o `users:read`. Estas son las
bloques de construcción.

**2. Roles**

Colecciones de permisos agrupados por función. Roles como `admin`,
`issuer`, o `viewer`.

**3. Asignaciones**

Vinculación de usuarios o claves API a roles. Un usuario puede tener múltiples roles.

## Permisos disponibles

### Permisos de atestación

| Permiso | Descripción |
| - | - |
| `attestations:mint` | Crear nuevas atestaciones |
| `attestations:read` | Ver detalles de atestación y descargar paquetes de prueba |
| `attestations:revoke` | Revocar atestaciones existentes |
| `attestations:*` | Todos los permisos de atestación |

### Permisos del emisor

| Permiso | Descripción |
| - | - |
| `issuers:read` | Ver información y claves del emisor |
| `issuers:write` | Crear emisores, registrar claves |
| `issuers:*` | Todos los permisos del emisor |

### Permisos de gestión de usuarios

| Permiso | Descripción |
| - | - |
| `users:read` | Ver usuarios y asignaciones de roles |
| `users:write` | Invitar usuarios, asignar roles, eliminar usuarios |
| `api-keys:read` | Ver claves API (sin secretos) |
| `api-keys:write` | Crear y revocar claves API |

### Permisos administrativos

| Permiso | Descripción |
| - | - |
| `audit:read` | Consultar registros de auditoría |
| `governance:approve` | Aprobar solicitudes de gobernanza |
| `governance:suspend` | Suspender emisores activos |
| `*` | Superadministrador: todos los permisos |

### Permisos de webhook

| Permiso | Descripción |
| - | - |
| `webhooks:read` | Ver puntos finales de webhook y registros de entrega |
| `webhooks:write` | Crear, actualizar y eliminar puntos finales |
| `webhooks:*` | Todos los permisos de webhook |

### Permisos de gobernanza

| Permiso | Descripción |
| - | - |
| `governance:read` | Ver solicitudes de gobernanza |
| `governance:approve` | Aprobar solicitudes de gobernanza |
| `governance:suspend` | Suspender emisores activos |
| `governance:*` | Todos los permisos de gobernanza |

### Permisos de configuración

| Permiso | Descripción |
| - | - |
| `settings:read` | Ver configuración de inquilino y organización |
| `settings:write` | Actualizar marca, dominios, correo electrónico y otras configuraciones |
| `settings:*` | Todos los permisos de configuración |

## Roles del sistema

Truthlocks aprovisiona un conjunto de roles del sistema automáticamente cuando se crea su inquilino. Los roles del sistema no se pueden editar ni eliminar.

| Rol | Descripción | Permisos clave |
| :- | :- | :- |
| **Administrador de inquilinos** | Acceso completo a todos los recursos dentro del inquilino | `*` (superadministrador) |
| **Administrador de organización** | Gestionar emisores, usuarios y atestaciones de una sola organización | `issuers:*`, `attestations:*`, `users:*`, `audit:read` |
| **Administrador de emisor** | Gestionar emisores y acuñar atestaciones | `issuers:*`, `attestations:*` |
| **Auditor** | Acceso de solo lectura para monitoreo y cumplimiento | `attestations:read`, `issuers:read`, `audit:read` |

Puede ver los roles del sistema desde la página **Roles** en la consola. Cada rol muestra su nombre, descripción y una insignia de **Sistema**.

## Roles personalizados

Cree roles personalizados para definir permisos de acceso adaptados a la estructura de su equipo. Los roles personalizados están disponibles en todos los planes.

### Creación de un rol personalizado en la consola

**1. Abrir la página de Roles**

Navega a **Roles** en la barra lateral de la consola.

**2. Haga clic en Crear rol personalizado**

El botón **Crear rol personalizado** abre un diálogo donde debe proporcionar:

* **Nombre del rol** — un nombre descriptivo para el rol (por ejemplo, `Developer` o `Compliance Officer`).
* **Descripción** — una breve explicación de para qué sirve el rol.

**3. Guardar el rol**

Haga clic en **Crear rol** para guardar. El nuevo rol aparece en la sección **Roles personalizados** de la página Roles.

### Creación de un rol personalizado a través de la API

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/roles \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "attestation_minter",
    "description": "Can only mint attestations for specific issuers",
    "permissions": ["attestations:mint", "attestations:read", "issuers:read"],
    "constraints": {
      "issuer_ids": ["issuer-uuid-1", "issuer-uuid-2"]
    }
  }'
```

### Restricciones a nivel de recurso

Los roles personalizados admiten restricciones opcionales que limitan los permisos a recursos específicos:

```json theme={null}
{
  "name": "regional_auditor",
  "description": "Audit access scoped to EU issuers only",
  "permissions": ["attestations:read", "issuers:read", "audit:read"],
  "constraints": {
    "issuer_ids": ["eu-issuer-uuid-1", "eu-issuer-uuid-2"]
  }
}
```

> [!NOTE]
>
> Las restricciones a nivel de recurso (como la limitación a emisores específicos) son
> disponible en planes Enterprise.

## Alcances de Clave API vs. Roles de Usuario

Tanto las claves API como los usuarios tienen permisos, pero funcionan de manera diferente:

| Aspecto | Ámbitos de clave API | Roles de usuario |
| - | - | - |
| Asignación | Establecida en la creación de la clave, inmutable | Puede cambiarse en cualquier momento |
| Pista de auditoría | Acciones registradas como ID de clave API | Acciones registradas como correo electrónico de usuario |
| Múltiple | Una clave = un conjunto de alcances | El usuario puede tener múltiples roles |
| Caso de uso | Integración de servidor a servidor | Usuarios humanos a través de UI/panel de control |

## Mejores prácticas

* **Menor privilegio:** Conceda solo los permisos necesarios para cada rol
* **Separación de funciones:** No asigne a un mismo rol tanto `attestations:mint` como `governance:approve`
* **Auditorías Regulares:** Revise las asignaciones de roles trimestralmente
* **Use claves de API para la automatización:** No comparta credenciales de usuario para scripts
* **Documentar roles personalizados:** Mantenga un registro de por qué se crearon los roles personalizados

## Próximos pasos

> [card] [Registros de Auditoría](https://docs.truthlocks.com/security/audit.md)
>
> Rastree todos los eventos relacionados con permisos.

> [card] [API de identidad](https://docs.truthlocks.com/api-reference/identity/orgs.md)
>
> Gestiona usuarios y roles programáticamente.


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