La mayoría de los plugins de WordPress que necesitan una clave de API la guardan en el mismo sitio que la descripción corta de la web: una página de ajustes que escribe en la tabla de opciones. Si necesitas guardar claves de API en WordPress, hoy hay lugares mejores. WordPress 7.2, previsto para el 8 de diciembre de 2026, añade una Secrets API que los plugins pueden usar para guardarlas cifradas. Te contamos dónde guardamos las credenciales en las webs de nuestros clientes, qué cambia la nueva API, el código que usamos para dar soporte a ambas opciones y el checklist que revisamos antes de entregar un proyecto.
Por qué las claves de API en la tabla de opciones son un problema
Un campo de ajustes es el camino fácil y, durante años, fue el único que ofrecía el núcleo. La propuesta de la Secrets API lo dice claramente: los plugins que necesitan una clave de API la escriben en texto plano en la tabla de opciones, así que la clave acaba en cada volcado de la base de datos, en cada copia de seguridad, en cada clon de staging y en cada wp option get que se ejecuta en un terminal compartido.
Ese es el riesgo real. Nadie tiene que hackear la web. Alguien envía una exportación de la base de datos a un freelance, una copia de staging se queda en un servidor barato o una captura de soporte muestra la página de ajustes. Cada una de esas copias es una clave válida para tu cuenta de Stripe, HubSpot o Mailchimp.
El texto plano en la base de datos, además, es difícil de limpiar. Una vez que una clave ha estado en wp_options, está en todas las copias de seguridad hechas desde entonces. Moverla a un sitio más seguro protege el futuro, no el pasado. Eso solo se arregla rotando la clave en el proveedor.
Dónde guardamos hoy las claves de API en WordPress
En el código que escribimos, una credencial nunca va a la tabla de opciones. Vive en uno de estos dos sitios, los dos fuera de la base de datos:
- Variables de entorno definidas en el panel del hosting o en la configuración del servidor. Es nuestra primera opción cuando el hosting lo permite, porque el valor nunca toca un archivo que despleguemos.
- Constantes en
wp-config.php, que no está en el repositorio de Git ni forma parte de una exportación de la base de datos.
Lipid Atlas es un buen ejemplo. La plataforma WordPress se comunica con un dataset privado en Hugging Face y con un motor de cálculo en Python en un Space privado. Los tokens de esas conexiones siguen la misma regla: son configuración del servidor, no ajustes del escritorio. El equipo del cliente edita planes, textos y datos desde el escritorio. Contamos el resto de ese desarrollo en vender acceso a datos con WordPress.
Los plugins de terceros que solo ofrecen un campo de ajustes son la excepción. Los anotamos en el checklist de entrega que verás más abajo y rotamos sus claves de forma periódica.
El inconveniente es que un editor sin perfil técnico no puede cambiar la clave desde el escritorio. Para credenciales, creemos que es lo correcto por defecto. Cambiar una clave de pagos debe ser un paso deliberado, no un campo que alguien edita por error.
Qué cambia la Secrets API de WordPress 7.2
La nota de desarrollo de la Secrets API describe una API del núcleo para credenciales como claves de API y secretos de cliente OAuth. WordPress 7.2 está programado para el 8 de diciembre de 2026, y la nota se revisó durante la beta, así que vuelve a consultarla antes de construir sobre ella.
Qué hace
- Los secretos se cifran con libsodium (XChaCha20-Poly1305) y se siguen guardando en las tablas de opciones. Sus claves se derivan de una clave raíz aleatoria, que a su vez se cifra con una nueva constante
WP_SECRETS_KEYenwp-config.php. wp_get_secret()devuelve un objetoWP_Secret. Si se imprime, se registra en un log o se vuelca, muestra un marcador como[secret:my-plugin/api-key]. Soloreveal()devuelve el valor.- Al escribir un valor nuevo se conserva el anterior, así que puedes rotar una clave sin romper peticiones que ya están en curso.
wp_import_option_as_secret()copia una opción existente en un secreto y la marca para rotación.- Los hostings pueden sustituir el almacenamiento o delegar toda la API en un gestor de secretos externo con un drop-in
secrets.php. En algunos hostings los valores se gestionan en su panel y WordPress solo puede leerlos. - Salud del sitio incorpora tres comprobaciones nuevas en Seguridad: una clave ausente o inutilizable, secretos que no se pueden descifrar y credenciales pendientes de rotación.
Qué no hace
No es un control de acceso. Los nombres usan un prefijo plugin-slug/secret-name, pero cualquier código que se ejecute en la web puede leer cualquier secreto. Las funciones tampoco comprueban capacidades, porque tienen que funcionar desde el cron y la API REST. Tu pantalla de ajustes sigue teniendo que comprobar quién introduce o gestiona un valor.
Tampoco protege frente a la ejecución de código dentro de WordPress. Un plugin comprometido puede leer un secreto, igual que puede leer wp-config.php o el entorno. De lo que protege la API es de la larga lista de copias: volcados, copias de seguridad, réplicas, exportaciones y capturas.
WP_SECRETS_KEY es el valor que no puedes perder
Las instalaciones nuevas reciben la clave automáticamente. En las webs existentes hay que añadirla a mano, y Salud del sitio genera la línea que hay que pegar debajo de las salts. Sin una clave utilizable, la API no guarda nada, y cada escritura y cada lectura de un secreto guardado devuelve un error.
La clave no es como las salts. La nota de desarrollo es explícita: una vez guardados los secretos, cambiar o eliminar WP_SECRETS_KEY los deja todos ilegibles hasta que vuelva el valor anterior. Eso cambia cómo tratamos las migraciones y las restauraciones. Una copia de la base de datos restaurada sin la WP_SECRETS_KEY correspondiente trae de vuelta secretos que nadie puede descifrar.
Leer una clave con alternativa para webs más antiguas
No todas las webs de nuestros clientes estarán en 7.2 el mismo día, y algunos hostings irán más lentos que otros. Por eso leemos las credenciales con una pequeña función auxiliar. Usa la Secrets API cuando está disponible y funciona, y si no, recurre al entorno y después a una constante.
/**
* Devuelve la clave de API del CRM, o null si no hay ninguna configurada.
* Llámala donde se usa la clave. No guardes nunca el resultado
* en una opción, un transient o un log.
*/
function pw_crm_api_key(): ?string {
if ( function_exists( 'wp_get_secret' ) ) {
$secret = wp_get_secret( 'pw-crm/api-key' );
if ( $secret instanceof WP_Secret ) {
return $secret->reveal();
}
if ( is_wp_error( $secret ) ) {
// Guardado, pero ilegible ahora mismo. No pidas una clave nueva.
error_log( 'pw-crm: secret unavailable (' . $secret->get_error_code() . ')' );
return null;
}
// null: nunca se guardó. Seguimos con la configuración del servidor.
}
$env = getenv( 'PW_CRM_API_KEY' );
if ( false !== $env && '' !== $env ) {
return $env;
}
return defined( 'PW_CRM_API_KEY' ) ? PW_CRM_API_KEY : null;
}Aquí importan dos detalles. wp_get_secret() devuelve null solo cuando el secreto nunca se guardó, y un WP_Error cuando existe pero no se puede leer. Si tu código trata ambos casos como «falta la clave» y pide una nueva, puede sobrescribir una credencial que todavía funciona. Por eso tampoco condicionamos las lecturas a wp_is_secrets_api_available(): devuelve false cuando la clave ha cambiado, y entonces un secreto guardado parecería ausente. Y la línea del log registra el código de error, nunca el valor.
Sacar una clave de wp_options
El núcleo no revisa la tabla de opciones por ti, porque no puede saber qué opciones son credenciales. Si un plugin que mantienes ya guarda ahí una clave, el traslado es un paso único al actualizar:
if ( function_exists( 'wp_is_secrets_api_available' )
&& wp_is_secrets_api_available()
&& false !== get_option( 'pw_crm_api_key' )
) {
$result = wp_import_option_as_secret( 'pw_crm_api_key', 'pw-crm/api-key' );
if ( true === $result ) {
// La importación deja la opción donde estaba. Bórrala tú.
delete_option( 'pw_crm_api_key' );
}
}Después, rota la clave en el proveedor. El secreto importado se marca para rotación por una buena razón: el valor antiguo sigue estando en todas las copias de seguridad hechas antes del traslado.
Nuestro checklist de credenciales para la entrega del proyecto
Esta es la lista que repasamos antes de que una web con integraciones salga en directo o pase al equipo del cliente o a un plan de mantenimiento.
- Inventario. Una línea por credencial: servicio, a qué cuenta pertenece, dónde se guarda y quién puede rotarla.
- Titularidad. Las claves se emiten desde la propia cuenta del cliente en el proveedor, no desde la nuestra.
- Ubicación. Ninguna credencial en el tema, en campos ACF ni en el repositorio de Git, y ninguna en la tabla de opciones salvo que un plugin de terceros no ofrezca alternativa. En ese caso se anota y se rota periódicamente. Todo lo demás va en variables de entorno, en
wp-config.phpo, a partir de 7.2, en la Secrets API. - Entornos. Staging y producción usan claves distintas, y claves de modo de prueba siempre que el proveedor las ofrezca. Un clon de staging nunca lleva una clave de pagos real.
- Alcance. Cada clave tiene los permisos mínimos que permite el proveedor para lo que hace la web.
- Exposición. Cualquier clave que haya estado en
wp_options, en un email o en un chat se rota antes del lanzamiento. - WordPress 7.2 y posteriores.
WP_SECRETS_KEYestá definida, guardada en el gestor de contraseñas del cliente y separada de las copias de la base de datos. Salud del sitio no muestra avisos de la Secrets API. - Documento de entrega. Dónde vive cada credencial y los pasos para rotarla, escritos para la persona que lo hará.
Trata WP_SECRETS_KEY como la llave de una caja fuerte, no como una salt. Haz una copia en un lugar distinto de la base de datos y no la cambies nunca sin seguir los pasos de la nota de desarrollo, o todos los secretos guardados dejarán de funcionar.
Si estás planificando una plataforma que conecte WordPress con pagos, un CRM o tus propios datos, esto forma parte de cómo desarrollamos plataformas de datos y aplicaciones web y desarrollo WordPress a medida.
FAQ
¿Es seguro guardar una clave de API en la página de ajustes de un plugin?
Funciona, pero salvo que el plugin use la Secrets API de WordPress 7.2, el valor va en texto plano a la tabla de opciones y, por tanto, a cada copia de seguridad y exportación de la base de datos. Mejor una variable de entorno o una constante en wp-config.php, o la Secrets API cuando tu web y el plugin la admitan.
¿La Secrets API impide que otros plugins lean mis claves?
No. Cualquier código que se ejecute en la web puede leer cualquier secreto. Protege las claves en las copias de la base de datos, como copias de seguridad, volcados y clones de staging, no frente al código dentro de WordPress.
¿Qué pasa si pierdo WP_SECRETS_KEY?
Los secretos guardados no se pueden descifrar hasta que vuelva el valor original. Salud del sitio lo indicará. Guarda la clave en un gestor de contraseñas, separada de tus copias de la base de datos.
¿Tengo que cambiar algo antes del 8 de diciembre?
No se rompe nada si esperas. Comprueba si tus plugins y tu hosting van a admitir la API, añade WP_SECRETS_KEY cuando actualices y aprovecha para sacar las claves que sigan en wp_options y rotarlas.