WordPress 7.2 (final release scheduled for 8 December) adds a Secrets API. Credentials such as API keys are stored encrypted, with one previous version kept for rotation. The Make Core dev note is the reference; these are the points that matter when you move an existing key out of a plain option.
1. Check availability first.
if ( ! wp_is_secrets_api_available() ) { return; // Keep the existing storage. } It returns false when the secrets.php drop-in failed to load, when WP_SECRETS_KEY is missing or unusable, or when the key can't decrypt the root key already stored.
2. Respect host-managed secrets. On a read-only provider, wp_secrets_provider_is_writable() returns false and wp_set_secret() returns a WP_Error. Show a notice instead of an input field, and don't fall back to an option.
3. Import, then clean up. wp_import_option_as_secret() copies the option into a secret. It leaves the option for you to delete and flags the secret for rotation, because the old value has already been through your backups.
4. Name it plugin-slug/secret-name. Lowercase letters, digits, hyphens and underscores, one slash. The prefix stops plugins from overwriting each other's secrets. It is not access control: any code on the site can read any secret.
5. Keep null and WP_Error apart.
$secret = wp_get_secret( 'my-plugin/api-key' ); if ( $secret instanceof WP_Secret ) { $client->authenticate( $secret->reveal() ); } elseif ( null === $secret ) { // Never stored: ask the admin for it. } else { // WP_Error: stored but unreadable right now. Don't ask for a new one. } 6. Call reveal() where you use the value. A WP_Secret prints as a placeholder when logged or JSON-encoded, and serializing or cloning it throws. Don't cache the object.
7. Check capabilities yourself. The functions don't, because they have to work from cron and REST. Check wherever a user enters or manages a value.
Source: The Secrets API in WordPress 7.2, Make WordPress Core, 11 Nov 2026 (updated 13 Nov).
Drafted with AI assistance and reviewed by the MammothWP team.
