> ## Documentation Index > Fetch the complete documentation index at: https://muveya.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Escopos > Todos os escopos de uma chave de API, o que cada um permite ler em /v1 e quais escopos OAuth o MCP usa, a permissão de membro correspondente e receitas de privilégio mínimo para integrações comuns. Um escopo é uma permissão concedida a uma chave de API na criação. Cada operação de `/v1` indica os escopos que exige, e o servidor os verifica em toda requisição. ## Como os escopos funcionam * **Forma com dois-pontos.** Os escopos da API são escritos `area:read` (por exemplo `inventory:read`). As permissões dos membros da equipe usam uma forma com ponto (`inventory.read`); o servidor traduz uma na outra com uma tabela fixa, mostrada abaixo. * **Todos os escopos exigidos precisam estar presentes.** Se uma operação exige um escopo que a chave não tem, a resposta é `403` com o código `api_keys.scope_missing`. A resposta não diz qual escopo está faltando. * **Sem curingas.** Não existe escopo "tudo" nem chave de plataforma. Não pode existir uma chave sem escopos. * **Nada é implícito.** `catalog:read` nunca concede `catalog.cost:read`; uma chave que precisa de custos deve ter os dois. * **Somente leitura.** Todos os escopos são de leitura. A única escrita de `/v1`, `POST /v1/analytics/exports`, é coberta por `analytics:read`. * **Fixos durante toda a vida da chave.** Não é possível adicionar nem remover escopos de uma chave existente. Peça uma chave nova com os escopos de que precisa e revogue a antiga (veja [Rotacionar uma chave](/docs/pt/api-reference/authentication#rotacionar-uma-chave)). * **`GET /v1/me` não exige escopo.** Use-a para ver os escopos de uma chave. ## Os escopos | Escopo | Operações que libera | Permissão de membro correspondente | Observações | | - | - | - | - | | `clinics:read` | `GET /v1/clinics`, `GET /v1/warehouses` | `clinics.read` | Unidades e depósitos com nome, tipo e status. Não existe permissão de membro com esse nome em **Equipe**; ela existe apenas para as chaves. | | `catalog:read` | `GET /v1/catalog/items`, `GET /v1/catalog/items/{itemId}`, `GET /v1/catalog/categories` | `catalog.read` (**Ler catálogo**) | Insumos do catálogo de qualquer status, sem custo. | | `catalog.cost:read` | Nenhuma operação sozinho | `catalog.cost.read` (**Ver custos dos materiais**) | Adiciona `cost`, `currency`, `costStatus` e `costMeasurement` aos insumos do catálogo, e `unitCost` e `currency` às linhas de pedido. Combine com `catalog:read` ou `orders:read`. | | `inventory:read` | `GET /v1/inventory/balances`, `GET /v1/inventory/boxes/{boxId}`, `GET /v1/inventory/boxes/{boxId}/balance`, `GET /v1/inventory/boxes/{boxId}/movements` | `inventory.read` (**Ver estoque**) | Quantidades, detalhes das caixas e movimentos do registro. Sem dinheiro. | | `orders:read` | `GET /v1/orders`, `GET /v1/orders/{orderId}` | `orders.read.all` (**Ver todos os pedidos**) | Todos os pedidos da clínica odontológica. Nunca inclui o `value` do pedido nem o `patientRef`. | | `fulfillment:read` | `GET /v1/fulfillments`, `GET /v1/fulfillments/{orderId}` | `fulfillment.read` (**Ver atendimento**) | Registros de entrega e histórico de custódia. | | `analytics:read` | Todas as operações `GET /v1/analytics/...`, `POST /v1/analytics/exports` e `GET /v1/analytics/exports/{exportId}` | `reports.read` (**Ver relatórios**) | Contagens, quantidades e durações agregadas. | ### Como as análises leem outros dados Para calcular seus números, uma operação de análise lê pedidos, estoque e entregas no servidor, com um acesso de leitura limitado a esse cálculo. Ela nunca expõe um custo, um valor de pedido ou uma referência de paciente, e não libera as outras operações para a chave: uma chave que tem apenas `analytics:read` continua recebendo `403` em `GET /v1/orders`. ## O que nenhum escopo concede | Dado ou ação | Por que uma chave nunca tem acesso | | - | - | | Totais de pedidos (`value`, `approvalPlan.evaluatedValue`) | Exigem a permissão de membro `orders.value.read` (**Ver valores dos pedidos**), que não corresponde a nenhum escopo da API. | | Referências de pacientes (`patientRef`) | Exigem `orders.patient_ref.read` (**Ver referências externas de pacientes**), que não corresponde a nenhum escopo da API. | | Criar ou alterar pedidos, estoque, catálogo, membros ou chaves | `/v1` não tem essas operações. Use o console. | | Aprovar, separar, despachar, confirmar entrega ou recebimento | São atos de uma pessoa. Uma chave não é um membro da equipe. | ## Escopos OAuth no MCP O endpoint MCP `/mcp` usa OAuth, não a chave de API de `/v1`. Uma ferramenta só funciona se o aplicativo recebeu o escopo e a pessoa ainda possui a permissão correspondente. Caso contrário, retorna `common.forbidden`. | Ferramenta ou recurso MCP | Escopo OAuth | | - | - | | `clinics.list`, `inventory.check` | `inventory:read` | | `catalog.search` | `catalog:read`, mais `catalog.cost:read` para custos | | `orders.get` | `orders:read` | | `analytics.consumption`, `management.briefing`, `management.compare_clinics` | `analytics:read` | | `approvals.list_pending`, `management.pending_decisions`, `fulfillment.get_pick_list` | Indisponíveis nos escopos OAuth atuais de somente leitura. | | Recursos de referência | Qualquer conexão OAuth ativa. | | `muveya://tenant/approval-policy-summary` | Indisponível nos escopos OAuth atuais de somente leitura. | Veja [Ferramentas MCP](/docs/pt/mcp/tools) e [Recursos MCP](/docs/pt/mcp/resources). ## Uma chave não é um membro da equipe A permissão correspondente é o que o servidor verifica, mas uma chave é diferente de uma pessoa que tem essa mesma permissão: * Uma chave lê **todas as unidades e depósitos** da sua clínica odontológica. O acesso a unidades e depósitos que você configura para os membros em **Equipe** não se aplica a ela. * Uma chave nunca vê valores de pedidos nem referências de pacientes, mesmo que um proprietário possa conceder essas permissões a uma pessoa. * Uma chave depende do membro para quem foi criada: veja [Quando uma chave deixa de funcionar](/docs/pt/api-reference/authentication#quando-uma-chave-deixa-de-funcionar). ## Receitas de privilégio mínimo Peça apenas os escopos que a integração usa. Cada escopo a mais amplia o que uma chave vazada exporia. | Integração | Escopos | | - | - | | Painel ou BI de níveis de estoque | `clinics:read`, `catalog:read`, `inventory:read` | | Sincronização de preços com compras ou ERP | `catalog:read`, `catalog.cost:read` | | Acompanhamento de pedidos em um ERP | `orders:read`, `fulfillment:read`, mais `clinics:read` para nomear unidades e depósitos | | Acompanhamento de pedidos com custo por linha | `orders:read`, `catalog.cost:read` | | Relatórios gerenciais e CSV semanal | `analytics:read` | | Assistente de IA somente leitura via MCP | `catalog:read`, `inventory:read`, `orders:read`, `analytics:read` | | Monitoramento de disponibilidade da integração | Um escopo que você já use; `GET /v1/me` em si não exige nenhum | Use uma chave diferente para cada integração, mesmo quando duas integrações precisam dos mesmos escopos. Assim você revoga uma sem afetar a outra, e cada uma tem seu próprio orçamento de [limites de uso](/docs/pt/api-reference/rate-limits). ## Páginas relacionadas * [Autenticação](/docs/pt/api-reference/authentication) * [Funções e permissões](/docs/pt/account/roles-and-permissions) * [Custos](/docs/pt/catalog/costs) * [Erros](/docs/pt/api-reference/errors) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.