Saltar al contenido

Guía

Crear una clave de API

Automatizaciones e integraciones · 7 min de lectura

Una clave de API permite que un desarrollador, o una herramienta que tú uses, utilice la Open API de Mateflow para leer y escribir los datos de tu comunidad. Creas, reemplazas y revocas las claves de API en Admin → Configuración → Integraciones → Acceso a la API. Cada clave funciona solo para una comunidad.

Quién puede hacerlo: los propietarios y administradores. · Dónde: web (consola de administración). · Plan: el acceso a la API, y cuántas solicitudes a la API al día puede hacer tu comunidad, dependen de tu plan de la plataforma.

Las claves de API son por comunidad

Las claves de API pertenecen a una sola comunidad, y las solicitudes hechas con una clave siempre actúan sobre esa comunidad. Para conectar varias comunidades, crea una clave en la consola de administración de cada una.

El panel de creador (app.mateflow.com) no tiene claves de API. Las claves del espacio de trabajo que había allí se han sustituido por claves por comunidad. La página Resumen de una comunidad en el panel enlaza a su página Integraciones.

Crear una clave de API

  1. Ve a Admin → Configuración → Integraciones y abre la pestaña Acceso a la API.
  2. Haz clic en Generar nueva clave.
  3. Escribe un Nombre de la clave que indique para qué sirve, como la herramienta que la usará y lo que hace. Los recordatorios de caducidad mencionan el nombre de la clave, así que un nombre claro te dice a qué integración se refieren.
  4. Opcional: activa Solo contenido público, por ejemplo, si vas a dar la clave a un tercero para mostrar contenido público. Consulta Limitar una clave al contenido público más abajo.
  5. En Ámbitos y permisos, marca solo los permisos que necesita la integración. Consulta la siguiente sección.
  6. En Caduca, deja Sin caducidad o elige 30 días, 90 días, 180 días o 365 días. El formulario muestra la fecha y la hora exactas en que la clave deja de funcionar.
  7. Opcional: en Lista blanca de IP (opcional), escribe las direcciones o rangos de IP que pueden usar la clave, separados por comas.
  8. Haz clic en Generar nueva clave.
  9. Copia la clave desde Clave de API generada, guárdala en un lugar seguro y haz clic en Listo.

Solo puedes ver la clave completa una vez. Si la pierdes, crea una clave de reemplazo y revoca la anterior.

No puedes cambiar los permisos, la caducidad ni el ajuste Solo contenido público de una clave después de crearla. Para cambiarlos, crea una clave de reemplazo (consulta más abajo).

Si la pestaña Acceso a la API muestra un aviso para mejorar el plan, tu plan de la plataforma no incluye el acceso a la API. La tarjeta Endpoint de la API muestra la URL base de las solicitudes y el límite diario de solicitudes de tu plan, que se restablece a las 00:00 UTC.

Ámbitos (permisos) de las claves de API

Los permisos se organizan en una fila por tipo de datos, con una casilla para cada acción. Cada casilla es un ámbito:

Fila Casilla Qué permite
Comunidad Leer Leer el perfil, la configuración y los metadatos de la comunidad
Contenido Leer Leer publicaciones, feeds, respuestas y resultados de búsqueda
Contenido Escribir Crear, editar y eliminar publicaciones y respuestas
Medios Leer Leer las URL firmadas de los archivos multimedia existentes
Medios Subir Solicitar tokens de subida; también permite leer las URL firmadas de los archivos multimedia
Espacios Leer Listar los espacios y leer sus detalles
Miembros Leer Buscar miembros y leer sus perfiles básicos, incluidos sus grupos de acceso
Miembros Invitar Invitar a personas por correo electrónico o con un enlace de invitación

Leer en Comunidad está marcado cuando se abre el formulario. Marcar Escribir o Subir no marca Leer por ti: una herramienta que solo crea publicaciones necesita solo Escribir en Contenido.

La fila Miembros aparece en Acceso sensible. Leer permite a la integración comprobar si una dirección de correo electrónico pertenece a tu comunidad. Con Invitar, las invitaciones se envían en nombre del propietario de la comunidad salvo que la integración indique otro remitente, y las personas invitadas siempre se unen como miembros. Las invitaciones por API pueden incluir grupos de acceso. Consulta Cómo funcionan los grupos de acceso.

Las claves más antiguas pueden mostrar Todos (heredado): conservan solo los ámbitos que existían cuando se crearon. Crea una clave nueva para usar ámbitos más recientes.

Limitar una clave al contenido público

Con Solo contenido público activado, una clave solo ve lo que ve un visitante sin sesión. Eso incluye el nombre y la descripción de los espacios privados, pero no los de los espacios secretos. Úsalo para una clave que le des a un tercero o para una herramienta que solo muestre contenido público.

Sin esta opción, una clave puede leer como cualquier miembro que indique la integración, incluido un administrador, lo que da acceso a los espacios privados y de pago. Esto también ocurre con una clave que solo tenga marcadas casillas de Leer, así que solo lectura no significa solo contenido público.

Una clave de este tipo solo puede tener Leer en Comunidad, Contenido y Espacios. Al activar la opción, las demás casillas se desmarcan y se desactivan. Las solicitudes que indican un miembro se rechazan. En la lista Claves de API, la clave muestra la etiqueta Solo público. Las claves que ya tienes no se ven afectadas.

Cuando caduca una clave de API

Una clave con caducidad deja de funcionar en la fecha y la hora que se mostraron al crearla. Las solicitudes que aún la usen se rechazan con un error que indica a tu desarrollador que la clave ha caducado, y no que se haya revocado o escrito mal.

En la lista Claves de API, la columna Estado muestra una cuenta atrás: Caduca en 62 días, y en horas el último día. La cuenta atrás cambia a un color de advertencia cuando quedan 14 días o menos. Pasa el cursor por encima para ver la fecha y la hora exactas. Cuando la clave ha caducado, su estado es Expirada.

Los propietarios y administradores reciben un recordatorio 14 días antes de que caduque una clave, 1 día antes y cuando caduca. Cada recordatorio es una notificación más un correo electrónico, e indica cuándo se usó la clave por última vez, para que sepas si algo sigue dependiendo de ella. Haz clic en la notificación para abrir Acceso a la API con la clave resaltada. En la app de Mateflow, la notificación muestra los mismos datos, pero no abre nada. El correo se envía de inmediato, aunque Notificaciones por correo esté desactivado en tus ajustes de notificaciones o recibas tus correos en un resumen Diario o Semanal. Solo dejas de recibirlo por correo si has desactivado el correo de Avisos del sistema o has puesto Correo resumen de notificaciones (antes llamado Frecuencia del resumen) en Desactivado. Las claves revocadas no generan recordatorios.

La caducidad no se puede ampliar. Para que una integración siga funcionando, reemplaza la clave antes de que caduque.

Reemplazar una clave de API

Al reemplazar una clave obtienes una clave nueva con la misma configuración, así que puedes hacer el cambio sin interrupciones: puedes tener varias claves a la vez. También es la forma de añadir una caducidad a una clave que no la tiene.

  1. En la pestaña Acceso a la API, abre el menú de acciones de la clave y haz clic en Crear reemplazo. Cuando a una clave le quedan 14 días o menos, o ya ha caducado, su fila también muestra un botón Reemplazar.
  2. Crear clave de reemplazo se abre con el nombre, los permisos, el ajuste Solo contenido público, la lista blanca de IP y la caducidad de la clave anterior ya rellenados. Cambia lo que necesites y haz clic en Generar nueva clave. Si la clave anterior tiene un permiso que este formulario no puede conceder, una nota «No se copió» lo indica, y la nueva clave no lo tendrá.
  3. Copia la nueva clave y ponla en tu integración.
  4. Cuando la integración use la nueva clave y esta muestre una hora en Último uso, haz clic en Revocar clave anterior en Siguiente: retira la clave anterior y confirma, o revoca la clave anterior desde la lista más adelante. Hasta que lo hagas, seguirás recibiendo recordatorios de caducidad de la clave anterior.

Las dos claves tienen el mismo nombre. Distínguelas por el prefijo de la clave, debajo del nombre, y por la fecha de Creada.

Revocar una clave de API

  1. En la pestaña Acceso a la API, busca la clave en Claves de API.
  2. Abre su menú de acciones y haz clic en Revocar clave.
  3. Confirma. La revocación no se puede deshacer, y cualquier herramienta que use la clave deja de funcionar.

La lista muestra el Estado de cada clave (Activa, Expirada o Revocada) y la fecha de Último uso. Las solicitudes a la API no aparecen en Registros de entrega, así que Último uso es la forma de comprobar si una clave se sigue usando. Desconectar Slack, Discord o Zapier no revoca ninguna clave de API. La creación y la revocación de claves quedan registradas en Admin → Configuración → Registro de auditoría, en Integraciones.

Mantener seguras las claves de API

  • Guarda las claves de API en un servidor, no en un sitio web ni en una app que otros puedan descargar, y envía las solicitudes por HTTPS.
  • Da a cada herramienta su propia clave con solo los ámbitos que necesita, para poder revocar una sin romper las demás.
  • Activa Solo contenido público en una clave que solo muestre contenido público, sobre todo si se la das a un tercero.
  • Define una caducidad y reemplaza las claves periódicamente, para que una clave que se filtre sin que lo sepas deje de funcionar por sí sola.
  • Añade una Lista blanca de IP cuando la herramienta llame desde direcciones fijas.
  • Revoca una clave de inmediato si puede haberse filtrado y después crea una de reemplazo.

Dónde encontrar la documentación de la API

La referencia de la API describe los endpoints, los formatos de solicitud y respuesta, los ámbitos, los códigos de error y ejemplos de código. En la pestaña Acceso a la API, la tarjeta Documentación para desarrolladores tiene un botón Abrir documentación que lleva a mateflow.com/developers. Envía ese enlace a tu desarrollador. No necesita una cuenta en tu comunidad, y la página está disponible aunque tu plan no incluya el acceso a la API.

Artículos relacionados

¿Te resultó útil esta guía?

Volver a las guías

¿No encuentras lo que necesitas?

Si eres miembro de una comunidad, sus administradores son quienes pueden ayudarte. Si estás creando o gestionando una en Mateflow, nuestro equipo puede ayudarte.