Scopes

Esta página se genera desde src/services/scope-catalog.ts —el catálogo que el backend consulta en cada llamada— y desde la tabla de rutas que gasta esos permisos. No puede nombrar un scope que no existe, y la columna «Qué abre» se vuelve a contar en cada build: es el número de operaciones que hoy lo exigen, no una cifra escrita a mano.

El capítulo que explica cómo se emite, se lee y se revoca una credencial está en Autenticación y API keys.

Qué es un scope

Un permiso con la forma recurso:acción. Lo que va antes de los dos puntos es el recurso; lo que va después, qué se puede hacer con él. Una credencial lleva los suyos en una lista y no tiene ninguno más.

• Una operación puede aceptar varios scopes, y le basta uno. El middleware que la protege recibe varios y los evalúa como un O: si la credencial lleva cualquiera de ellos, pasa. Por eso una misma operación aparece contada en más de una fila.
• Nadie reparte lo que no tiene. Al emitir una credencial, la plataforma rechaza todo scope que no lleve quien la está emitiendo. Una API key nunca sale más ancha que la persona o la credencial que la creó.
• * existe y no es para ti. Es el comodín de las credenciales de arranque de la plataforma. Ningún rol lo lleva, y el formulario de emisión no lo acepta.
• El scope no es toda la puerta. Dice qué familia de operaciones se puede llamar, no qué registros se pueden ver: encima siguen aplicando la visibilidad por registro y, cuando corresponde, la del inventario publicado. Un scope abre la ruta; no decide qué devuelve.
• Un scope sin ruta no es un scope muerto. Unos pocos protegen un campo dentro de otra respuesta, una herramienta del servidor MCP o un trabajo en segundo plano, y alguno está reservado para una operación que todavía no existe. La tabla lo dice en vez de esconderlos.

Cómo se lee una fila

• Scope — la cadena exacta que va en scopes al emitir la credencial. La tabla va ordenada por esa cadena, así que los scopes de un mismo recurso quedan juntos.
• Qué abre — cuántas operaciones de la API lo exigen hoy, seguidas de las áreas del contrato a las que llegan. Cuando el área es uno de los capítulos que publica este sitio, va enlazada; si no, va el nombre de la etiqueta tal como aparece en el contrato. Al final va el tier de esas operaciones: estable cambia solo con aviso de obsolescencia, beta puede cambiar con una entrada de changelog, interna no es parte de la API pública y puede cambiar sin aviso.
• Roles — cuáles de los cuatro roles integrados lo llevan. Un rol personalizado se arma con cualquier scope de administrador, nunca con uno de dueño.
• Marcas — solo dueño cuando ningún administrador lo lleva; sensible cuando alguna de sus operaciones toca datos personales o de salud que exceden los de contacto habituales; preset de conector cuando lo incluye la conexión guiada de una aplicación conectada; pk_ cuando lo lleva una llave publicable de navegador.

Todos los scopes

Son 182 scopes: los que reparten los roles integrados, más los del preset de conector y los de las llaves publicables. Las grafías en desuso están al final de la página.

El preset de conector

Lo que emite la conexión guiada de una aplicación conectada: un permiso de lectura por cada familia de herramientas que expone el perfil del conector, y nada más. No es un rol, y ninguna persona lo lleva.

Dentro va mcp:connector, que no es un permiso: no protege ninguna ruta, ninguna herramienta, ningún campo ni ninguna columna. Su único efecto es quitarle capacidad a quien lo lleva —el servidor MCP ve la marca y reduce su catálogo a un perfil de solo lectura—, y por eso puede viajar a la vista en la credencial: no hay nada a lo que escalar. Una credencial con esta marca y nada más puede hacer estrictamente menos que una credencial sin nada.

• analytics:read
• appointment_types:read
• appointments:read
• clinic:read
• contacts:read
• conversations:read
• followups:read
• help_centers:read
• leads:read
• marketplace:read
• mcp:connector
• pipelines:read
• price_approval:read
• teams:read
• tenant:read
• tickets:read
• vehicle_pipeline:read

La lectura de márgenes y costos no viene incluida: se añade marcando la casilla correspondiente al conectar, y sin ese scope esas herramientas ni siquiera aparecen en el catálogo.

Las llaves publicables pk_

Una llave pk_ vive en el navegador, así que no lleva scopes propios: la plataforma le resuelve este conjunto fijo en cada petición. Ningún rol lo reparte y el formulario de emisión no lo ofrece; una pk_ no puede llevar un permiso de escritura amplio ni uno de administración.

• appointments:intake
• leads:intake
• stock:read
• storefront_events:write
• widget:chat

Agregar una entrada a este conjunto se lo concede a todas las pk_ que ya existen, sin volver a emitirlas — por eso la lista es corta y cada entrada abre una sola superficie pública.

Grafías en desuso

Un puente de una sola versión: quien lleva la cadena antigua es tratado como si llevara la nueva, y nada más cambia. La grafía en desuso no se puede repartir, no la ofrece ningún rol y no la acepta el formulario de emisión — solo sigue funcionando en las credenciales que ya la tenían.