---
title: "WordPress 7.2 Secrets API: How To Store API Keys Safely"
url: https://nexterwp.com/blog/wordpress-7-2-secrets-api/
date: 2026-11-12
modified: 2026-11-12
lang: en
author: "Aditya Sharma"
description: "WordPress 7.2 adds a Secrets API that encrypts API keys and tokens. Learn the functions, WP_SECRETS_KEY setup, breaking changes and what it means for AI."
image: https://nexterwp.com/wp-content/uploads/2026/11/wordpress-7-2-secrets-api-featured-1024x538.webp
word_count: 1841
---

# WordPress 7.2 Secrets API: How To Store API Keys Safely

## Key Takeaways

- WordPress 7.2 Secrets API stores API keys, tokens and passwords encrypted instead of as plain text in the options table.
- WP_SECRETS_KEY lives in wp-config.php and wraps the encryption key, so a database dump on its own is no longer enough to read secrets.
- wp_set_secret(), wp_get_secret(), wp_delete_secret() and wp_list_secrets() handle encrypted secrets, while wp_list_secrets() returns names and metadata, never values.
- Site Health adds three Secrets tests that check whether WP_SECRETS_KEY is defined, whether the provider is working and writable, and whether plaintext options still need migration.
- Beta 1 changes require developers to define WP_SECRETS_KEY and change custom keyrings, stores and providers from implements to extends or face a fatal error.

WordPress 7.2 ships a new Secrets API, a core way for plugins to store API keys, tokens and passwords encrypted instead of as plain text in the options table. It uses libsodium XChaCha20-Poly1305 encryption, a root key called `WP_SECRETS_KEY` in wp-config.php, and a small set of functions such as `wp_set_secret()` and `wp_get_secret()`. The final dev note was published on 11 November 2026, and it includes two breaking changes from Beta 1 that plugin developers need to act on now.

This guide explains what the Secrets API is, how it works, how to set up the key, what changed since the beta, and what it means for site owners who connect AI providers, payment gateways and email services to WordPress.

Table of Contents

## Why WordPress Needed A Secrets API

Almost every modern site stores credentials. An SMTP plugin keeps a mail password. A payment plugin keeps gateway keys. An AI plugin keeps an OpenAI or Anthropic API key. Until now, each plugin decided on its own how to store these, and most saved them as plain text in the `wp_options` table.

That creates real risk. A leaked database backup, a SQL injection bug in any plugin, or a staging copy shared with a contractor can expose every key on the site at once. WordPress 7.0 made this more urgent by adding the AI Client and Connectors, which encourage sites to store provider keys. The [Secrets API proposal](https://make.wordpress.org/core/2026/08/25/proposal-a-secrets-api-for-wordpress-7-2/) from August 2026 set out to give every plugin one shared, encrypted place for these values, tracked in [Trac ticket #66187](https://core.trac.wordpress.org/ticket/66187).

***Also Read:** [WordPress 7.2: Everything Coming In The Next Release](https://nexterwp.com/blog/wordpress-7-2/)*

## How The WordPress Secrets API Works

The API has three layers. Each one is an abstract class that a host or security plugin can replace.

- **Keyring** (`WP_Secrets_Keyring`): holds the root key that wraps every other key.
- **Store** (`WP_Secrets_Store`): decides where encrypted values live. The default store uses the options table.
- **Provider** (`WP_Secrets_Provider`): ties the keyring and store together and exposes the public functions.

By default, each secret is encrypted with libsodium’s XChaCha20-Poly1305 and saved to the database. The encryption key is itself wrapped by `WP_SECRETS_KEY`, which lives in wp-config.php and never in the database. So a database dump on its own is no longer enough to read your keys.

Hosts and enterprise teams can swap the default storage by placing a `wp-content/secrets.php` drop-in. That drop-in can send secrets to a cloud key vault or a hardware module while plugins keep calling the same functions.

## Secrets API Functions In WordPress 7.2

![Table of WordPress 7.2 Secrets API functions and what they do](https://nexterwp.com/wp-content/uploads/2026/11/wordpress-7-2-secrets-api-functions.webp)The main Secrets API functions, summarised from the core dev note of 11 November 2026.

- `wp_set_secret( $name, $value )`: stores or updates an encrypted secret.
- `wp_get_secret( $name )`: returns a `WP_Secret` object, `null` if it was never stored, or a `WP_Error` on failure.
- `wp_delete_secret( $name )`: removes a secret.
- `wp_list_secrets()`: returns names and metadata, never values.
- `wp_import_option_as_secret( $option, $name )`: copies an existing option into the vault and flags it for rotation.
- `wp_retire_secret_version( $name )`: deletes the previous version after a rotation.
- `wp_is_secrets_api_available()` and `wp_secrets_provider_is_writable()`: let a plugin check support before using it.
- Network variants such as `wp_set_network_secret()` for multisite-wide values.

Secret names use a `plugin-slug/name` format, for example `my-smtp/password`. This keeps plugins from overwriting each other’s values.

### A Basic Example

`if ( function_exists( 'wp_is_secrets_api_available' ) && wp_is_secrets_api_available() ) {
wp_set_secret( 'my-plugin/api-key', $api_key );

$secret = wp_get_secret( 'my-plugin/api-key' );
if ( $secret instanceof WP_Secret ) {
$client->authenticate( $secret->reveal() );
}
}`

The `WP_Secret` object masks its value when printed, logged or dumped. You only get the real string by calling `reveal()`, which makes accidental leaks through debug logs much less likely.

### Rotation And The Change Hook

When you update a secret, WordPress keeps the previous version so you can roll over safely, for example while a remote service still accepts the old key. Once the new key works, call `wp_retire_secret_version()` to delete the old one. Every change fires the `wp_secret_changed` action, so a plugin can clear caches or re-register a webhook when a key changes.

### No Built-In Capability Checks

The functions do not check user capabilities. That is deliberate, because secrets are often read during cron jobs or REST requests where there is no logged-in admin. It also means the plugin is responsible for checking `current_user_can()` before it lets anyone view or change a secret through a settings screen.

## How To Set Up WP_SECRETS_KEY

New installs of WordPress 7.2 add the key to wp-config.php automatically. Existing sites that update need one in place. Site Health can generate one for you, or you can add it by hand.

- Back up wp-config.php before you edit it.
- Generate a random 32-byte key on the command line with the command below.
- Open wp-config.php and add the define above the line that says “That’s all, stop editing!”.
- Save the file and open Tools, then Site Health, to confirm the Secrets tests pass.
- Store a copy of the key in your password manager. Without it, saved secrets cannot be decrypted.

`php -r 'echo base64_encode( random_bytes( 32 ) ), "\n";'

// wp-config.php
define( 'WP_SECRETS_KEY', 'paste-your-generated-key-here' );`

**Important:** do not rotate this key the way you might refresh your salts. Changing `WP_SECRETS_KEY` without the migration steps below makes every stored secret unreadable. Also make sure the same key goes with the site when you move it to a new host or clone it to staging.

## Site Health Checks For Secrets

![Site Health tests added by the WordPress 7.2 Secrets API](https://nexterwp.com/wp-content/uploads/2026/11/wordpress-7-2-secrets-api-site-health.webp)The three Site Health tests that report on the Secrets API.

WordPress 7.2 adds three Site Health tests. They check that the key is defined, that the provider is working and writable, and whether any plaintext options are still waiting to be moved into the vault. If you see a warning after updating, start here. It is the fastest way to know whether your site is ready.

## Breaking Changes Since Beta 1

Developers who tested early builds need to know about two changes in the final version.

![Breaking changes in the WordPress 7.2 Secrets API since Beta 1](https://nexterwp.com/wp-content/uploads/2026/11/wordpress-7-2-secrets-api-breaking.webp)What changed between Beta 1 and the final Secrets API.

- **The key is now required.** Beta 1 could fall back to deriving a key. The final API expects `WP_SECRETS_KEY` to be defined.
- **Interfaces became abstract classes.** Custom keyrings, stores and providers must change `implements` to `extends`. Code that still uses `implements` causes a fatal error.

`// Beta 1 (now fatal)
class My_Vault_Store implements WP_Secrets_Store { }

// WordPress 7.2 final
class My_Vault_Store extends WP_Secrets_Store { }`

### Migrating A Beta Site

If you stored secrets on a beta build with a derived key, the dev note describes a three-step move to a real key.

- Define your old key as `WP_SECRETS_KEY_PREVIOUS` and your new key as `WP_SECRETS_KEY`.
- Run the `rotate_site_key` routine so each secret is re-wrapped with the new key.
- Once Site Health is green, remove `WP_SECRETS_KEY_PREVIOUS` from wp-config.php.

## Moving Existing Plugin Options Into The Vault

Plugins with years of installs already have keys sitting in options. The cleanest path is gradual:

- On update, check `wp_is_secrets_api_available()`.
- If it is available, call `wp_import_option_as_secret()` to copy the old option into the vault.
- Read from the vault first and fall back to the option only on older WordPress versions.
- Delete the plaintext option once the import succeeds, and ask the user to rotate the key at the provider, since the old value may already have been exposed.

`function my_plugin_get_api_key() {
if ( function_exists( 'wp_get_secret' ) ) {
$secret = wp_get_secret( 'my-plugin/api-key' );
if ( $secret instanceof WP_Secret ) {
return $secret->reveal();
}
}
return get_option( 'my_plugin_api_key', '' );
}`

For sites still on WordPress 7.0 or 7.1, the [Secrets API feature plugin](https://github.com/ericmann/secrets-api) provides the same functions, with full docs at [secretsapi.dev](https://secretsapi.dev/). That lets you write against one API today and drop the plugin once 7.2 is everywhere.

***Also Read:** [WordPress Core Security Initiative Explained](https://nexterwp.com/blog/wordpress-core-security-initiative/)*

## What The Secrets API Means For Site Owners

You do not need to write code to benefit. Once your plugins adopt the API, the keys you paste into settings screens are encrypted at rest without any extra step. Here is what to do as a site owner:

- After updating to 7.2, open Site Health and fix any Secrets warnings.
- Back up wp-config.php alongside your database. A database backup without the key cannot restore your secrets.
- When you clone a site to staging, decide on purpose whether the staging copy should share the live key or get its own.
- Watch plugin changelogs for “Secrets API” support, especially SMTP, payment, backup and AI plugins.
- Rotate old API keys at the provider once a plugin moves them into the vault.

## Why This Matters For AI On WordPress

The timing is not an accident. WordPress 7.0 added the AI Client and Connectors, and the Abilities API lets AI assistants act on a site through tools exposed by plugins. Every AI connection starts with a provider key. The Secrets API gives those keys a safe home, which matters more as sites connect several AI providers at once.

It also changes how you should think about agent access. Because `wp_get_secret()` has no capability check, plugins that expose abilities to AI agents must never return secret values through those abilities. A well-built ability uses a key internally and returns only the result. Nexter follows this pattern: its 150+ AI Abilities, available through any MCP plugin, let AI assistants build pages and manage settings without ever handing provider keys back to the agent.

To learn more about how core AI features are moving, read our coverage of the [WordPress AI plugin 1.5.0](https://nexterwp.com/blog/wordpress-ai-plugin-1-5-0/) release.

## Secrets API FAQ

### Which WordPress version includes the Secrets API?

WordPress 7.2. Older versions can use the feature plugin.

### Where are secrets stored?

Encrypted in the options table by default. A `secrets.php` drop-in can move them to an external vault.

### What happens if I lose WP_SECRETS_KEY?

Stored secrets cannot be decrypted. You would need to enter every key again, so keep a safe copy.

### Can I rotate WP_SECRETS_KEY like my salts?

No. Use `WP_SECRETS_KEY_PREVIOUS` and the rotation routine, or your secrets become unreadable.

### Does the API stop admins from seeing keys?

Not by itself. It encrypts keys at rest. Who can view them in the dashboard still depends on each plugin’s capability checks.

## What This Doesn’t Cover

This guide is based on the [official Secrets API dev note](https://make.wordpress.org/core/2026/11/11/the-secrets-api-in-wordpress-7-2/) published on 11 November 2026. It does not walk through writing a full custom keyring or store, configuring a specific cloud key vault, or which plugins have adopted the API so far. WordPress 7.2 is still in beta, so details may change before the final release. Check the dev note for updates.

## Wrapping Up

The Secrets API is one of the most practical security changes in WordPress 7.2. It gives every plugin one encrypted place for API keys, keeps the root key out of the database, and supports rotation and external vaults. Site owners should check Site Health and back up wp-config.php. Developers should switch `implements` to `extends`, start importing old options, and keep secret values out of anything an AI agent can read.

#### Suggested Reading

- [WordPress 7.2: Everything Coming In The Next Release](https://nexterwp.com/blog/wordpress-7-2/)
- [WordPress 7.2 SVG Admin Icons](https://nexterwp.com/blog/wordpress-7-2-svg-admin-icons/)
- [WordPress 7.2 Random Post URL](https://nexterwp.com/blog/wordpress-7-2-random-post-url/)
- [WordPress Core Security Initiative](https://nexterwp.com/blog/wordpress-core-security-initiative/)
- [Gutenberg 24.4 Release Candidate](https://nexterwp.com/blog/gutenberg-24-4-release-candidate/)

#### Stay updated with Helpful WordPress Tips, Insider Insights, and Exclusive Updates – Subscribe now to keep up with Everything Happening on WordPress!

Subscribe

## Frequently Asked Questions

**Q: Why is the WordPress Secrets API better than storing API keys in wp_options?**
A: The main win is that secrets are encrypted at rest instead of sitting as plain text in the wp_options table. That matters because a leaked database backup, a SQL injection bug, or a shared staging copy can expose every key on the site at once. WordPress 7.2 uses libsodium XChaCha20-Poly1305 and keeps the root key in wp-config.php, so a database dump alone is not enough to read the values.

**Q: What happens if WP_SECRETS_KEY is missing or lost?**
A: Without WP_SECRETS_KEY, existing secrets cannot be decrypted. New installs of WordPress 7.2 add it automatically, but existing sites need it in wp-config.php before the Secrets API can work properly. If the key is lost, the practical outcome is re-entering every secret again, which is why the guide says to store a copy in a password manager and back up wp-config.php alongside the database.

**Q: How do I know if my site is ready for the Secrets API?**
A: Site Health is the quickest check because WordPress 7.2 adds three tests for this feature: whether WP_SECRETS_KEY is defined, whether the provider is working and writable, and whether any plaintext options still need to be moved into the vault. If you see a warning after updating, that screen tells you whether the problem is missing configuration or leftover unencrypted data.

**Q: Can older WordPress versions use the Secrets API for plugin keys?**
A: WordPress 7.0 and 7.1 can use the feature plugin, which exposes the same functions and has full docs at secretsapi.dev. That lets plugin developers write against one API now and then drop the plugin once 7.2 is everywhere. The page also notes that [WordPress Core Security Initiative Explained](https://nexterwp.com/blog/wordpress-core-security-initiative/) covers the broader security direction behind this change.

**Q: What should plugin developers change after the final Secrets API release?**
A: Two beta-era assumptions break in the final version: WP_SECRETS_KEY is now required, and custom keyrings, stores, and providers must extend abstract classes instead of implementing interfaces. Code that still uses implements will fatal. That means beta code needs a real root key in wp-config.php and updated class definitions before it can run on WordPress 7.2.

**Q: How should I migrate existing plugin options into the Secrets API vault?**
A: The clean path is to import old options gradually with wp_import_option_as_secret(), then read from the vault first and fall back to get_option() only on older WordPress versions. Once import succeeds, delete the plaintext option and ask users to rotate the provider key because the old value may already have been exposed. For AI-heavy sites, this matters even more because [WordPress AI plugin 1.5.0](https://nexterwp.com/blog/wordpress-ai-plugin-1-5-0/) shows how quickly provider keys become part of normal site operations.