Escopos

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).
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 e Recursos MCP.

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.

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.

Visão geral

Endpoints

Como os escopos funcionam

Os escopos

Como as análises leem outros dados

O que nenhum escopo concede

Escopos OAuth no MCP

Uma chave não é um membro da equipe

Receitas de privilégio mínimo

Páginas relacionadas

​Como os escopos funcionam

​Os escopos

​Como as análises leem outros dados

​O que nenhum escopo concede

​Escopos OAuth no MCP

​Uma chave não é um membro da equipe

​Receitas de privilégio mínimo

​Páginas relacionadas

Como os escopos funcionam

Os escopos

Como as análises leem outros dados

O que nenhum escopo concede

Escopos OAuth no MCP

Uma chave não é um membro da equipe

Receitas de privilégio mínimo

Páginas relacionadas