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

<!-- i18n: source=docs/reference/operations/grants.md blob=2f19ca501aab2dc4bc26f5ffd268d4f65aa8e98f model=claude-sonnet-5-5 -->
> Esta página é uma tradução automática da [página em 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>

# Operações de `grants`

Os campos exatos que cada operação `grants.*` recebe e retorna.

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

Toda op é `POST /v1/<op>` via HTTP e a ferramenta MCP `loom_<op>`. Os campos de identidade (`org`, `namespace`, `agent`, `user_id`, `session_id`) são preenchidos a partir do token e da sessão MCP quando o transporte consegue fazer isso; em uma chamada HTTP sem token em um servidor de usuário único, é preenchida a org da instalação em todas as ops, exceto `code.*` e `tracker.*` (que mantêm a org do próprio plano), e, em [algumas ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request), também o namespace e o agente; veja [identidades e namespaces](https://clickhouse.github.io/loom/pt-BR/concepts/identities-and-namespaces/). O [índice de operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica role, kind e a listagem `all` do MCP. Campos de entrada desconhecidos são atendidos e listados em `ignored_args`.

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

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

## `grants.approve`

Aprova (ou rejeita) uma solicitação de concessão pendente.

`POST /v1/grants.approve` · MCP `loom_grants_approve` · papel `admin` · idempotente · auditado · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `subject` | `str` | obrigatório | De quem é a solicitação pendente a decidir: um e-mail ou uma claim `sub` de conta de serviço. |
| `decision` | `Literal['approve', 'reject']` | `'approve'` | `approve` ativa o papel solicitado (ou o papel substituto); `reject` descarta a solicitação, mantendo qualquer papel base, ou remove a linha quando o subject não tinha acesso base. |
| `role` | `Literal['viewer', 'writer', 'admin'] \| None` | `None` | Aprova com um papel diferente do solicitado (uma solicitação de mantenedor respondida como leitor). |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `subject` | `str` | O subject como a solicitação o escreveu. |
| `namespace` | `str` | O namespace que a op lê ou grava. |
| `decision` | `Literal['approve', 'reject']` | A decisão aplicada (repete a solicitação). |
| `role` | `Literal['viewer', 'writer', 'admin'] \| None` | O papel aprovado (em `reject`, o papel que a solicitação teria tido); None quando não existia linha de concessão para o subject. |
| `decided_at` | `datetime` | Quando a decisão foi gravada (UTC). |

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

## `grants.create`

Concede a outro sujeito (usuário ou conta de serviço) o papel de viewer / writer / admin em um namespace.

`POST /v1/grants.create` · MCP `loom_grants_create` · papel `admin` · idempotente · auditado

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou escreve. |
| `subject` | `str` | obrigatório | Um login, um e-mail (ele admite uma conta assim que esse e-mail é verificado: o de uma conta SSO ou o de uma conta vinculada) ou a claim `sub` de uma conta de serviço. |
| `role` | `Literal['viewer', 'writer', 'admin']` | obrigatório | `viewer`, `writer` ou `admin`; um namespace de código aceita apenas `viewer` (leitor) e `admin` (mantenedor). |
| `granted_by` | `str` | `'admin'` | Ignorado quando há autenticação: o servidor registra o chamador autenticado. |
| `replace` | `bool` | `False` | A tabela substitui por (org, namespace, subject), então um create abaixo do papel ativo atual do sujeito o rebaixaria silenciosamente. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `org` | `str` | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | O namespace que a op lê ou escreve. |
| `subject` | `str` | O sujeito como a requisição o escreveu (a linha é armazenada sob o login da conta cujo e-mail verificado ele é; caso contrário, como foi escrito). |
| `role` | `Literal['viewer', 'writer', 'admin']` | O papel agora ativo para o sujeito. |
| `granted_at` | `datetime` | Quando a linha da concessão foi gravada (UTC). |

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

## `grants.list`

Lista as concessões ativas em um namespace: quem tem acesso e com qual papel.

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

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `limit` | `int` | `100` | Linhas por página, uma por pessoa, com a concessão mais recente primeiro; de 1 a 500. |
| `cursor` | `str \| None` | `None` | Retoma a página anterior no mesmo namespace; deixe sem definir na primeira página. |
| `fields` | `list[str] \| None` | `None` | Os campos de saída que o chamador lê (uma lista de permissão resolvida contra o modelo da linha; um nome desconhecido resulta em 422); sem definir, todos os campos. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `rows` | `list[_GrantEntry]` | Concessões vigentes no namespace, ativas e pendentes (as revogadas são excluídas), da mais recente para a mais antiga; uma linha por pessoa, com as outras grafias dela em `also`. |
| `next_cursor` | `str \| None` | Passe como `cursor` para obter a próxima página; None quando esta página é a última. |
| `truncated` | `bool` | True quando há mais pessoas depois desta página (`next_cursor` está definido). |

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

## `grants.pending_for_me`

Todas as solicitações pendentes nos namespaces que o chamador administra, em uma única instrução.

`POST /v1/grants.pending_for_me` · MCP `loom_grants_pending_for_me` · role `viewer` · leitura · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `limit` | `int` | `500` | No máximo esta quantidade de solicitações, das mais recentes para as mais antigas; de 1 a 2,000. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `rows` | `list[_PendingForMeEntry]` | Solicitações pendentes de entrada ou de elevação nos namespaces que o chamador administra, das mais recentes para as mais antigas; vazio para um chamador anônimo. |

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

## `grants.revoke`

Remove a concessão de um sujeito em um namespace.

`POST /v1/grants.revoke` · MCP `loom_grants_revoke` · role `admin` · idempotente · auditado · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `subject` | `str` | obrigatório | De quem revogar a concessão: um login handle, um e-mail ou o `sub` de uma conta de serviço; a linha da pessoa em cada grafia verificada é removida, e uma solicitação pendente é rejeitada. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `revoked` | `bool` | True quando alguma das linhas de concessão do sujeito foi encontrada e revogada; false quando não havia nenhuma. |
| `revoked_at` | `datetime \| None` | Quando a revogação foi gravada (UTC); None quando nada foi revogado. |

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

## `grants.share_agent`

Permite que outro agente do mesmo trust do chamador leia, ou escreva, no namespace do próprio chamador.

`POST /v1/grants.share_agent` · MCP `loom_grants_share_agent` · role `writer` · idempotente · auditado · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace do próprio agente chamador, o único que ele pode compartilhar. |
| `grantee` | `str` | obrigatório | O agente do mesmo trust com quem compartilhar, conforme o nome dado pelo seu plano de controle. |
| `role` | `Literal['viewer', 'writer']` | `'viewer'` | O que esse agente pode fazer ali: `viewer` lê, `writer` também escreve. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `namespace` | `str` | O namespace que a op lê ou escreve. |
| `subject` | `str` | O subject sob o qual o grant é armazenado, `sa:<trust>:<agent>`. |
| `role` | `Literal['viewer', 'writer']` | O role agora ativo para esse agente. |
| `granted_at` | `datetime` | Quando a linha do grant foi gravada (UTC). |

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

## `grants.unshare_agent`

Retira o que o chamador emprestou a outro agente da sua confiança.

`POST /v1/grants.unshare_agent` · MCP `loom_grants_unshare_agent` · role `writer` · idempotente · auditado · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace do próprio agente que faz a chamada. |
| `grantee` | `str` | obrigatório | O agente da mesma confiança cujo grant deve ser revogado. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `revoked` | `bool` | True quando o agente tinha um grant e ele foi revogado. |
| `revoked_at` | `datetime \| None` | Quando a revogação foi gravada (UTC); None quando nada foi revogado. |

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