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

# Scopes

> Todos los scopes de una clave de API, qué permite leer cada uno en /v1 y qué scopes OAuth usa MCP, el permiso de miembro al que corresponde y recetas de mínimo privilegio para integraciones comunes.

Un scope es un permiso que se otorga a una clave de API al crearla. Cada operación de `/v1` indica los scopes que requiere, y el servidor los verifica en cada solicitud.

## Cómo funcionan los scopes

* **Forma con dos puntos.** Los scopes de la API se escriben `area:read` (por ejemplo `inventory:read`). Los permisos de los miembros del equipo usan una forma con punto (`inventory.read`); el servidor traduce uno en otro con una tabla fija, que se muestra más abajo.
* **Se necesitan todos los scopes requeridos.** Si una operación requiere un scope que la clave no tiene, la respuesta es `403` con el código `api_keys.scope_missing`. La respuesta no dice qué scope falta.
* **Sin comodines.** No existe un scope "todo" ni una clave de plataforma. No puede existir una clave sin scopes.
* **Nada es implícito.** `catalog:read` nunca otorga `catalog.cost:read`; una clave que necesita costos debe tener ambos.
* **Solo lectura.** Todos los scopes son de lectura. La única escritura de `/v1`, `POST /v1/analytics/exports`, queda cubierta por `analytics:read`.
* **Fijos durante toda la vida de la clave.** No se pueden agregar ni quitar scopes a una clave existente. Pide una clave nueva con los scopes que necesitas y revoca la anterior (consulta [Rotar una clave](/docs/es/api-reference/authentication#rotar-una-clave)).
* **`GET /v1/me` no requiere scope.** Úsala para ver los scopes de una clave.

## Los scopes

| Scope | Operaciones que habilita | Permiso de miembro al que corresponde | Notas |
| - | - | - | - |
| `clinics:read` | `GET /v1/clinics`, `GET /v1/warehouses` | `clinics.read` | Sedes y bodegas con nombre, tipo y estado. No existe un permiso de miembro con este nombre en **Equipo**; solo existe para las claves. |
| `catalog:read` | `GET /v1/catalog/items`, `GET /v1/catalog/items/{itemId}`, `GET /v1/catalog/categories` | `catalog.read` (**Leer catálogo**) | Insumos del catálogo de cualquier estado, sin costo. |
| `catalog.cost:read` | Ninguna operación por sí solo | `catalog.cost.read` (**Ver costos de insumos**) | Agrega `cost`, `currency`, `costStatus` y `costMeasurement` a los insumos del catálogo, y `unitCost` y `currency` a las líneas de pedido. Combínalo con `catalog:read` u `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 inventario**) | Cantidades, detalle de cajas y movimientos del registro. Sin dinero. |
| `orders:read` | `GET /v1/orders`, `GET /v1/orders/{orderId}` | `orders.read.all` (**Ver todos los pedidos**) | Todos los pedidos de la clínica dental. Nunca incluye el `value` del pedido ni el `patientRef`. |
| `fulfillment:read` | `GET /v1/fulfillments`, `GET /v1/fulfillments/{orderId}` | `fulfillment.read` (**Ver abastecimiento**) | Registros de entrega e historial de custodia. |
| `analytics:read` | Todas las operaciones `GET /v1/analytics/...`, `POST /v1/analytics/exports` y `GET /v1/analytics/exports/{exportId}` | `reports.read` (**Ver reportes**) | Conteos, cantidades y duraciones agregadas. |

### Cómo lee otros datos la analítica

Para calcular sus cifras, una operación de analítica lee pedidos, existencias y entregas en el servidor, con un acceso de lectura limitado a ese cálculo. Nunca expone un costo, un valor de pedido ni una referencia de paciente, y no habilita las demás operaciones para la clave: una clave que solo tiene `analytics:read` sigue recibiendo `403` en `GET /v1/orders`.

## Lo que ningún scope otorga

| Dato o acción | Por qué una clave nunca lo obtiene |
| - | - |
| Totales de pedidos (`value`, `approvalPlan.evaluatedValue`) | Requieren el permiso de miembro `orders.value.read` (**Ver valores de pedidos**), al que no corresponde ningún scope de la API. |
| Referencias de pacientes (`patientRef`) | Requieren `orders.patient_ref.read` (**Ver referencias externas de pacientes**), al que no corresponde ningún scope de la API. |
| Crear o cambiar pedidos, existencias, catálogo, miembros o claves | `/v1` no tiene esas operaciones. Usa la consola. |
| Aprobar, preparar, despachar, confirmar entrega o recepción | Son actos de una persona. Una clave no es un miembro del equipo. |

## Scopes OAuth en MCP

El endpoint MCP `/mcp` usa OAuth, no la clave de API de `/v1`. Una herramienta solo funciona si la aplicación recibió el scope y la persona conserva el permiso correspondiente. De otro modo devuelve `common.forbidden`.

| Herramienta o recurso MCP | Scope OAuth |
| - | - |
| `clinics.list`, `inventory.check` | `inventory:read` |
| `catalog.search` | `catalog:read`, más `catalog.cost:read` para costos |
| `orders.get` | `orders:read` |
| `analytics.consumption`, `management.briefing`, `management.compare_clinics` | `analytics:read` |
| `approvals.list_pending`, `management.pending_decisions`, `fulfillment.get_pick_list` | No disponibles en los scopes OAuth actuales de solo lectura. |
| Recursos de referencia | Cualquier conexión OAuth activa. |
| `muveya://tenant/approval-policy-summary` | No disponible en los scopes OAuth actuales de solo lectura. |

Consulta [Herramientas MCP](/docs/es/mcp/tools) y [Recursos MCP](/docs/es/mcp/resources).

## Una clave no es un miembro del equipo

El permiso correspondiente es lo que verifica el servidor, pero una clave se diferencia de una persona que tiene ese mismo permiso:

* Una clave lee **todas las sedes y bodegas** de su clínica dental. El acceso a sedes y bodegas que configuras para los miembros en **Equipo** no se le aplica.
* Una clave nunca ve valores de pedidos ni referencias de pacientes, aunque un propietario pueda otorgar esos permisos a una persona.
* Una clave depende del miembro para quien se creó: consulta [Cuando una clave deja de funcionar](/docs/es/api-reference/authentication#cuando-una-clave-deja-de-funcionar).

## Recetas de mínimo privilegio

Pide solo los scopes que la integración usa. Cada scope adicional amplía lo que expondría una clave filtrada.

| Integración | Scopes |
| - | - |
| Tablero o BI de niveles de existencias | `clinics:read`, `catalog:read`, `inventory:read` |
| Sincronización de precios con compras o ERP | `catalog:read`, `catalog.cost:read` |
| Seguimiento de pedidos en un ERP | `orders:read`, `fulfillment:read`, más `clinics:read` para nombrar sedes y bodegas |
| Seguimiento de pedidos con costo por línea | `orders:read`, `catalog.cost:read` |
| Reportes gerenciales y CSV semanal | `analytics:read` |
| Asistente de IA de solo lectura por MCP | `catalog:read`, `inventory:read`, `orders:read`, `analytics:read` |
| Monitoreo de disponibilidad de la integración | Un scope que ya uses; `GET /v1/me` por sí sola no requiere ninguno |

<Tip>
  Usa una clave distinta para cada integración, aunque dos integraciones necesiten los mismos scopes. Así puedes revocar una sin afectar la otra, y cada una tiene su propio presupuesto de [límites de uso](/docs/es/api-reference/rate-limits).
</Tip>

## Páginas relacionadas

* [Autenticación](/docs/es/api-reference/authentication)
* [Roles y permisos](/docs/es/account/roles-and-permissions)
* [Costos](/docs/es/catalog/costs)
* [Errores](/docs/es/api-reference/errors)


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