Cuando creas una clave de API de cuenta en Provedly, tomas una decisión: Read only (solo lectura) o Read and write (lectura y escritura). Es una elección pequeña que determina cuánto puede hacer un asistente de IA o un script con tu cuenta, y vale la pena acertar el primer día en lugar de después de que pase algo inesperado.
Qué permite cada nivel
| Acción | Read only | Read and write |
|---|---|---|
| Ver plan, límites y uso | Sí | Sí |
| Listar sitios, widgets y barras | Sí | Sí |
| Leer estadísticas (impresiones, clics, pedidos) | Sí | Sí |
| Obtener el fragmento de instalación | Sí | Sí |
| Pausar o reactivar un widget | No | Sí |
| Crear una barra, editarla, pausarla o reactivarla | No | Sí |
| Añadir un registro | No | Sí |
| Marcar un registro como verificado | No | No |
La última fila no es un error. Ninguna clave puede marcar nada como verificado, en ningún nivel. La verificación solo viene de los webhooks firmados de Stripe, Shopify y WooCommerce, y la API no tiene forma de saltárselo. Los registros añadidos con una clave de escritura conservan la fuente API, llevan una etiqueta visible "Imported" en el widget y nunca muestran la marca de verificado. Por qué tu asistente no puede verificar una compra explica el razonamiento.
La misma tabla se aplica tanto si la clave se usa mediante la API REST como mediante el servidor MCP. Una llamada a una herramienta es una llamada a la API con una cara más amable.
Cuál elegir
Una regla sencilla: dale a una clave lo mínimo que necesita para su trabajo, y crea una segunda clave cuando aparezca un segundo trabajo.
Informes y preguntas. Una revisión semanal de estadísticas, un script de panel, un asistente al que le preguntas "¿cómo fue la semana pasada?": solo lectura. Ninguno de estos necesita cambiar nada, y una clave de solo lectura filtrada permite a un desconocido leer tus cifras, pero no tocar tu sitio.
Gestionar campañas desde el chat. Si quieres decir "pausa la barra de Black Friday" o "crea la cuenta regresiva del lanzamiento" y que ocurra, el asistente necesita lectura y escritura. Esa es la idea del flujo de Black Friday desde el chat.
Backends que añaden compras. Un servidor que envía registros necesita lectura y escritura. Dale su propia clave, con el nombre del servicio, para poder rotarla sin tocar nada más.
Colaboradores externos y agencias. Una clave por persona, con su nombre. Cuando termine el trabajo, revócala. La parte de las agencias está en gestionar muchos sitios de clientes.
Protecciones que existen sea cual sea la clave
Incluso una clave de lectura y escritura funciona dentro de las mismas reglas que el panel, lo que limita el daño de los errores.
- Los límites del plan se mantienen. Reactivar un widget o activar una barra por encima del límite de tu plan se rechaza.
- Las barras nuevas empiezan en pausa. Una barra creada mediante la API o MCP no se muestra a los visitantes hasta que alguien la activa en un segundo paso. Un prompt malinterpretado o un script con errores produce un borrador en pausa, no un banner publicado.
- Nada pasa a ser verificado. Explicado arriba.
- La revocación es inmediata. Revoca una clave en Settings y la siguiente solicitud con ella falla.
Cómo manejar las claves
Las claves empiezan por provedly_ y se muestran una sola vez, al crearlas. Provedly no las vuelve a mostrar, así que no hay nada que recuperar; una clave perdida se revoca y se sustituye.
Donde acaban las claves es donde surgen la mayoría de los problemas. Algunos sitios a vigilar:
Archivos de configuración del cliente MCP. Claude Code y Cursor guardan la configuración de los servidores en archivos. Si añades el servidor a nivel de proyecto y el proyecto está en git, revísalo antes de hacer commit. La guía de Claude Code y la guía de Cursor indican dónde se guarda la clave.
Historial de la shell. Pon la clave en una variable de entorno o en un gestor de secretos en lugar de pegarla en un comando curl que luego encontrarás en el historial.
Código del navegador. Una clave en JavaScript del lado del cliente es pública. La API es para servidores, terminales y herramientas de IA, nunca para un script que se ejecuta en tu tienda. El script del widget no necesita ninguna clave.
Transcripciones del chat. No pegues la clave en el chat con tu asistente. Va en la cabecera Authorization de la configuración del servidor, desde donde el cliente la envía sin que el modelo necesite verla.
Si se filtra una clave
Revócala en Settings, crea una nueva y actualízala dondequiera que se usara la antigua. Después revisa qué cambió: la lista de barras y widgets muestra el estado actual, y los registros añadidos mediante la API muestran la fuente API en la pestaña Data del widget, así que son fáciles de localizar y eliminar. Como los registros de la API nunca pueden ser verificados, una clave filtrada no puede poner compras verificadas falsas en tu página de verificación.
Preguntas frecuentes
¿Puedo cambiar una clave de solo lectura a lectura y escritura?
Crea una clave nueva con el nivel que quieras y revoca la antigua. Mantener fijo el nivel de cada clave deja claro qué puede hacer cada una.
¿Deberían varias herramientas compartir una clave?
Funciona, pero las claves separadas son más fáciles de gestionar. Con una clave por herramienta o por persona, la pantalla de API keys te dice quién tiene acceso, y revocar una no rompe las demás.
¿El widget de mi sitio usa una de estas claves?
No. La etiqueta de script de tus páginas usa un token público del widget y no necesita ningún secreto. Las claves de API de cuenta son solo para la API REST y el servidor MCP.
Las claves están disponibles en todos los planes, Free incluido. Crea una cuenta para generar la primera.