WordPress 7.2 Secrets API: A Safer Way to Store Plugin Credentials
- Get link
- X
- Other Apps
WordPress 7.2 Secrets API: A Safer Way to Store Plugin Credentials
Plugin authors have traditionally had to choose between storing API keys in the options table, asking site owners to define constants, or building a private encryption layer. WordPress 7.2 introduces a core Secrets API that gives plugins a standard place to store credentials encrypted at rest.
This is a useful improvement, but it is not a reason to upgrade a production site to a beta without testing. WordPress 7.2 Beta 5 was released on November 10, 2026, the release candidate is scheduled for November 17, and the final release is scheduled for December 8. Treat the API as a feature to test now and adopt deliberately after the stable release.
What the Secrets API changes
The API provides four focused operations:
wp_set_secret()stores or updates a secret.wp_get_secret()retrieves a secret object.wp_delete_secret()removes a secret.wp_retire_secret_version()supports retiring an older version during rotation.
Secret names use a namespaced convention such as acme-orders/api-key. WordPress encrypts the value at rest using a key configured through the WP_SECRETS_KEY constant in wp-config.php. New installations receive that configuration automatically; existing installations need to follow the Site Health guidance to add it.
The API also leaves room for hosting-specific storage. A host can provide a secrets.php drop-in instead of relying on the default storage implementation. That matters for organizations whose policy requires a secrets manager or a different key-management boundary.
Read a secret without assuming success
wp_get_secret() does not simply return a string. It can return a WP_Secret object, null when the name is not present, or a WP_Error when the secret exists but cannot be read. The value is masked until the plugin explicitly calls reveal().
A small wrapper should preserve those distinctions instead of silently turning every failure into an empty credential:
<?php function acme_orders_get_api_key() { $secret = wp_get_secret( 'acme-orders/api-key' ); if ( is_wp_error( $secret ) ) { error_log( sprintf( 'Acme Orders could not read its API key: %s', $secret->get_error_message() ) ); return null; } if ( null === $secret ) { return null; } return $secret->reveal(); } The caller can now distinguish “not configured” from “configured but unavailable.” In an admin screen, use that distinction to show a useful setup message. In a request that calls an external service, fail explicitly and avoid sending a request with an empty or stale token.
Store and rotate credentials
When a site owner saves a new token, call wp_set_secret() with the same name. The API keeps a previous version so a rotation can be staged rather than treated as a destructive overwrite. The exact rotation policy still belongs to the plugin: decide when the new credential is verified, when the old one is retired, and how an administrator is told that the change failed.
A practical migration looks like this:
- Read the old option only when the new secret is absent.
- Write the value through
wp_set_secret(). - Verify the credential with the provider before deleting the legacy option.
- Remove the plaintext option after a successful migration and document the change in the plugin’s upgrade routine.
Do not copy the legacy value into logs, debug screens, REST responses, or an HTML data attribute while migrating. Encryption at rest does not protect a secret after the plugin reveals it, so keep the revealed value in the smallest possible scope and pass it directly to the client library that needs it.
Plan for WordPress versions
WordPress 7.2 is still in beta on the date of this post. A plugin that supports older sites should feature-detect the API rather than call the new functions unconditionally:
<?php function acme_orders_store_api_key( $api_key ) { if ( ! function_exists( 'wp_set_secret' ) ) { return new WP_Error( 'secrets_api_unavailable', 'This WordPress version does not provide the Secrets API.' ); } return wp_set_secret( 'acme-orders/api-key', $api_key ); } That guard is only the beginning of compatibility work. Test activation, upgrades, multisite behavior, missing WP_SECRETS_KEY configuration, failed reads, and a host-provided storage drop-in. Keep the existing credential path until the new path has been verified, but do not continue writing new plaintext values after a successful migration.
What the API does not solve
There is no secrets-management admin UI in WordPress 7.2. A plugin must still provide a careful settings flow, permission checks, validation, and a way to replace or revoke a credential. The API also does not protect a compromised PHP process, a malicious administrator, or a plugin that reveals the value into logs. Encryption at rest is one control, not a complete credential lifecycle.
The safest adoption strategy is therefore small and explicit: namespace every secret, check every return value, reveal values only at the integration boundary, migrate old options only after verification, and test against the 7.2 release candidates before depending on the API in production.
References
- WordPress Developer Blog: What’s new for developers? (November 2026)
- WordPress.org: WordPress 7.2 Beta 5
- Make WordPress Core: WordPress 7.2 Release Party Schedule
- WordPress Core Trac: Secrets API ticket #66187
❤️ Support This Blog
If this post helped you, you can support my writing with a small donation. Thank you for reading.
- Get link
- X
- Other Apps

Comments
Post a Comment