Skip to main content
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).
  • GET /v1/me no requiere scope. Úsala para ver los scopes de una clave.

​
Los scopes

​
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

​
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. Consulta Herramientas MCP y Recursos MCP.

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

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

​
Páginas relacionadas