Moving an API key from wp_options to the WordPress 7.2 Secrets API

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.