> Source: https://clickhouse.github.io/loom/es/reference/operations/grants/ (Markdown: https://clickhouse.github.io/loom/es/reference/operations/grants.md)

<!-- i18n: source=docs/reference/operations/grants.md blob=2f19ca501aab2dc4bc26f5ffd268d4f65aa8e98f model=claude-sonnet-5-5 -->
> Esta página es una traducción automática de la [página en inglés](https://clickhouse.github.io/loom/reference/operations/grants/), que prevalece.
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/grants/), which is authoritative.

<a id="grants-operations"></a>

# Operaciones de `grants`

Los campos exactos que recibe y devuelve cada operación `grants.*`.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Cada op es `POST /v1/<op>` sobre HTTP y la herramienta MCP `loom_<op>`. Los campos de identidad (`org`, `namespace`, `agent`, `user_id`, `session_id`) se completan a partir del token y de la sesión MCP cuando el transporte puede hacerlo; en una llamada HTTP sin token en un servidor de un solo usuario, se completa la org de la instalación en todas las ops excepto `code.*` y `tracker.*` (que conservan la de su plano), y en [algunas ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request) también su espacio de nombres y su agente; consulta [identidades y espacios de nombres](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md). El [índice de operaciones](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica el rol, el tipo y el listado `all` de MCP. Los campos de entrada desconocidos se atienden y se nombran en `ignored_args`.

<!-- prettier-ignore-start -->

<a id="grantsapprove"></a>

## `grants.approve`

Aprueba (o rechaza) una solicitud de concesión pendiente.

`POST /v1/grants.approve` · MCP `loom_grants_approve` · rol `admin` · idempotente · auditada · no aparece en el conjunto de herramientas MCP `all`

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str` | obligatorio | El espacio de nombres que la operación lee o escribe. |
| `subject` | `str` | obligatorio | De quién se decide la solicitud pendiente: un correo electrónico o un claim `sub` de una cuenta de servicio. |
| `decision` | `Literal['approve', 'reject']` | `'approve'` | `approve` activa el rol solicitado (o el de la sobrescritura); `reject` descarta la solicitud y conserva cualquier rol base, o elimina la fila cuando el sujeto no tenía acceso base. |
| `role` | `Literal['viewer', 'writer', 'admin'] \| None` | `None` | Aprueba con un rol distinto del solicitado (una solicitud de mantenedor respondida como lector). |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `subject` | `str` | El sujeto tal como lo escribió la solicitud. |
| `namespace` | `str` | El espacio de nombres que la operación lee o escribe. |
| `decision` | `Literal['approve', 'reject']` | La decisión aplicada (repite la de la solicitud). |
| `role` | `Literal['viewer', 'writer', 'admin'] \| None` | El rol aprobado (en `reject`, el rol que habría tenido la solicitud); None cuando no existía ninguna fila de concesión para el sujeto. |
| `decided_at` | `datetime` | Cuándo se escribió la decisión (UTC). |

<a id="grantscreate"></a>

## `grants.create`

Otorga a otro sujeto (usuario o cuenta de servicio) el rol de viewer / writer / admin sobre un espacio de nombres.

`POST /v1/grants.create` · MCP `loom_grants_create` · role `admin` · idempotent · audited

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str` | obligatorio | El espacio de nombres que la op lee o escribe. |
| `subject` | `str` | obligatorio | Un identificador de inicio de sesión, un correo electrónico (admite una cuenta una vez que ese correo está verificado: el de una cuenta SSO o el de una cuenta vinculada) o un claim `sub` de una cuenta de servicio. |
| `role` | `Literal['viewer', 'writer', 'admin']` | obligatorio | `viewer`, `writer` o `admin`; un espacio de nombres de código solo admite `viewer` (lector) y `admin` (mantenedor). |
| `granted_by` | `str` | `'admin'` | Se ignora cuando hay autenticación: el servidor registra al llamante autenticado. |
| `replace` | `bool` | `False` | La tabla reemplaza según (org, namespace, subject), así que un create con un rol inferior al rol activo actual del sujeto lo rebajaría en silencio. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `org` | `str` | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str` | El espacio de nombres que la op lee o escribe. |
| `subject` | `str` | El sujeto tal como lo escribió la solicitud (la fila se guarda bajo el identificador de inicio de sesión de la cuenta cuyo correo verificado es, o si no, tal como se escribió). |
| `role` | `Literal['viewer', 'writer', 'admin']` | El rol que está activo ahora para el sujeto. |
| `granted_at` | `datetime` | Cuándo se escribió la fila de la concesión (UTC). |

<a id="grantslist"></a>

## `grants.list`

Lista las concesiones activas en un espacio de nombres: quién tiene acceso y con qué rol.

`POST /v1/grants.list` · MCP `loom_grants_list` · role `viewer` · read

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str` | obligatorio | El espacio de nombres que la operación lee o escribe. |
| `limit` | `int` | `100` | Filas por página, una por persona, con la concesión más reciente primero; de 1 a 500. |
| `cursor` | `str \| None` | `None` | Reanuda la página anterior en el mismo espacio de nombres; sin definir para la primera página. |
| `fields` | `list[str] \| None` | `None` | Los campos de salida que lee el llamador (una lista blanca resuelta contra el modelo de fila; un nombre desconocido produce un 422); sin definir, todos los campos. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `rows` | `list[_GrantEntry]` | Concesiones vigentes en el espacio de nombres, activas y pendientes (se excluyen las revocadas), de la más reciente a la más antigua; una fila por persona, con sus otras grafías en `also`. |
| `next_cursor` | `str \| None` | Se pasa como `cursor` para obtener la página siguiente; None cuando esta página es la última. |
| `truncated` | `bool` | True cuando hay más personas después de esta página (`next_cursor` está definido). |

<a id="grantspending_for_me"></a>

## `grants.pending_for_me`

Todas las solicitudes pendientes en los espacios de nombres que administra quien llama, en una sola instrucción.

`POST /v1/grants.pending_for_me` · MCP `loom_grants_pending_for_me` · rol `viewer` · lectura · no aparece en el toolset `all` de MCP

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `limit` | `int` | `500` | Como máximo este número de solicitudes, de la más reciente a la más antigua; de 1 a 2,000. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `rows` | `list[_PendingForMeEntry]` | Solicitudes pendientes de unión o de elevación en los espacios de nombres que administra quien llama, de la más reciente a la más antigua; vacío si quien llama es anónimo. |

<a id="grantsrevoke"></a>

## `grants.revoke`

Elimina el permiso (grant) de un sujeto sobre un espacio de nombres.

`POST /v1/grants.revoke` · MCP `loom_grants_revoke` · rol `admin` · idempotente · auditada · no aparece en el toolset `all` de MCP

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str` | obligatorio | El espacio de nombres que la op lee o escribe. |
| `subject` | `str` | obligatorio | El sujeto cuyo grant se revoca: un nombre de usuario (login), un correo electrónico o el `sub` de una cuenta de servicio; se elimina la fila de la persona bajo cada grafía verificada y se rechaza una solicitud pendiente. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `revoked` | `bool` | True cuando se encontró y se revocó alguna de las filas de grant del sujeto; false cuando no tenía ninguna. |
| `revoked_at` | `datetime \| None` | Cuándo se escribió la revocación (UTC); None cuando no se revocó nada. |

<a id="grantsshare_agent"></a>

## `grants.share_agent`

Permite que otro agente de la misma confianza del llamador lea, o escriba, en el espacio de nombres propio del llamador.

`POST /v1/grants.share_agent` · MCP `loom_grants_share_agent` · rol `writer` · idempotente · auditado · no aparece en el toolset `all` de MCP

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str` | obligatorio | El espacio de nombres propio del agente que llama, el único que puede compartir. |
| `grantee` | `str` | obligatorio | El agente de la misma confianza con el que se comparte, tal como lo nombra su plano de control. |
| `role` | `Literal['viewer', 'writer']` | `'viewer'` | Lo que ese agente puede hacer allí: `viewer` lee, `writer` también escribe. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `namespace` | `str` | El espacio de nombres que la op lee o escribe. |
| `subject` | `str` | El sujeto bajo el que se almacena la concesión, `sa:<trust>:<agent>`. |
| `role` | `Literal['viewer', 'writer']` | El rol que ahora está activo para ese agente. |
| `granted_at` | `datetime` | Cuándo se escribió la fila de la concesión (UTC). |

<a id="grantsunshare_agent"></a>

## `grants.unshare_agent`

Retira lo que quien llama prestó a otro agente de su confianza.

`POST /v1/grants.unshare_agent` · MCP `loom_grants_unshare_agent` · rol `writer` · idempotente · auditado · no aparece en el toolset `all` de MCP

| Campo de entrada | Tipo | Valor por defecto | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). |
| `namespace` | `str` | obligatorio | El espacio de nombres propio del agente que llama. |
| `grantee` | `str` | obligatorio | El agente de la misma confianza cuya concesión se va a revocar. |

| Campo de salida | Tipo | Significado |
| --- | --- | --- |
| `revoked` | `bool` | True cuando el agente tenía una concesión y se revocó. |
| `revoked_at` | `datetime \| None` | Cuándo se escribió la revocación (UTC); None cuando no se revocó nada. |

<!-- prettier-ignore-end -->
