As of September 12, 2026, the Secrets API is not yet a confirmed WordPress 7.2 Core API: it is a pre-merge feature plugin. The proposal published on Make WordPress Core defines an encrypted storage interface for API keys, tokens, and other credentials, with WP-CLI support and extension points for external providers. The plan is to decide before WordPress 7.2 Beta 1 whether the API ships in that release or is deferred to 7.3. Developers can already test the design, but they should not treat the Core functions as guaranteed yet.
First: the API is not yet confirmed for WordPress 7.2 Core
The proposal was published on August 25, 2026 and was followed by a feature plugin so contributors and plugin authors can test the behavior before the Core patch. On September 10, the Dev Chat summary noted that an initial working implementation was available and asked for feedback, especially about interoperability with external providers.
The project repository describes its current state as “pre-core-merge”: the public surface of the feature plugin is settled, but the code has not yet been merged into WordPress. The 7.2 schedule places Beta 1 on October 20–22, 2026; the proposal itself treats that window as the practical deadline for landing the API, with an explicit option to defer it to 7.3 if it is not ready.
Primary sources: the Secrets API proposal, the feature plugin on GitHub, the September 9 Dev Chat summary, and the WordPress 7.2 schedule.
What problem the Secrets API is trying to solve
Core currently has no first-class abstraction for credentials. Plugins that need an API key or token usually rely on the Options API or custom mechanisms. That can leave sensitive values mixed with ordinary site data and copied into database dumps, backups, staging clones, and other operational workflows.
The proposal creates a common path for a plugin to say “this is a secret” and delegate storage, encryption, rotation, and infrastructure integration to WordPress or the hosting provider. The intended benefit is not to make the value unreadable to all PHP code; it is to reduce credential exposure at rest and create a single point for operations and auditing.
How the proposed storage model works
- Encryption is always on: there is no plaintext mode. The default implementation uses encryption at rest with a key hierarchy.
- Replaceable default storage: WordPress can keep encrypted records using the options infrastructure, while hosts can replace the provider, keyring, or store with KMS, HSM, or secret-service integrations.
- Dedicated drop-in: a wp-content/secrets.php file is the proposed integration point for alternative implementations.
- Two value slots: CURRENT and PREVIOUS support rotation without retaining unbounded history.
- Fail closed: if the secret backend or keyring is unavailable, the operation returns an error; the design rejects a silent fallback to weaker local storage.
- No plaintext export: the design does not provide a way to export secret values; migrations and staging environments are expected to receive credentials again.
The current feature plugin also separates three extension levels: WP_Secrets_Provider for platforms where an external system is the source of truth, WP_Secrets_Keyring to replace root-key protection, and WP_Secrets_Store to replace where records are kept.
How plugins would access a secret in code
The proposed API is intentionally small. The design exposes wp_set_secret() for writing, wp_get_secret() for reading, wp_delete_secret() for deletion, and wp_import_option_as_secret() for moving a known value from the Options API.
Reads are designed to distinguish three states: a WP_Secret object when a value exists and can be retrieved, null when it does not exist, and WP_Error when it exists but cannot be read, such as when key material or a backend fails. This prevents a plugin from confusing “missing credential” with “broken credential” and incorrectly restarting a connection flow.
Getting the raw string requires an explicit WP_Secret::reveal() call. The object also exposes a fingerprint() value, useful for comparison or auditing without exposing the secret itself. The naming convention is plugin-slug/secret-name, but the namespace is organizational: current documentation explicitly says it does not create strong isolation between plugins running in the same PHP process.
Where WP-CLI fits
WP-CLI is in scope for the 7.2 proposal because it serves as a first-party consumer and helps test whether the API is sufficient for real operational tasks. There is also an operational-security reason: credentials passed directly as shell arguments may end up in shell history or the process list. A native Secrets API integration can support read and write workflows that avoid that pattern.
However, the August proposal was still asking for feedback on which commands should exist and in what order. Documentation authors and automation maintainers should therefore avoid freezing the feature plugin's command names as if they were a final WordPress 7.2 interface until the Core merge and official documentation are in place.
How to migrate keys currently stored in wp_options
The proposal deliberately avoids automatic migration. Core cannot safely determine which options are credentials, and a heuristic sweep could move or break data that is not actually secret.
The proposed path is explicit: each plugin knows its old option name and decides, in its own upgrade routine, when to import it with wp_import_option_as_secret(). After import, the credential should be treated as a rotation candidate. Encrypting a token that has already traveled through backups, replicas, and caches does not erase historical copies; changing the value at the external service is what reduces that residual risk.
What is left out of the first version — and what is a non-goal
| Item | Status in the current design | Practical implication |
|---|---|---|
| Admin screen for managing secrets | Deferred; the proposal points to 7.3 | 7.2 prioritizes storage, access, and extensibility semantics rather than a full UI. |
| Strong isolation between plugins | Out of scope | Code running inside the same WordPress process can in principle access secrets; namespaces are not a privilege boundary. |
| Automatic migration of existing options | Not planned | Each plugin must migrate only the credentials it knows and control its own upgrade cycle. |
| Plaintext value export | Deliberately absent | New environments should receive the credential again instead of transporting a dump of secrets. |
| Protection against arbitrary code execution in the PHP process | Outside the threat model | The API hardens storage and accidental exposure, but it does not defeat an attacker who already executes code as WordPress. |
| Final WP-CLI command interface | Still subject to integration | Test the feature plugin, but wait for Core integration and documentation before depending on final syntax. |
How to prepare plugins and integrations now
- Inventory credentials: list API keys, tokens, integration passwords, and the options where they live today.
- Put reads and writes behind one layer: avoid scattering get_option() and update_option() throughout the plugin. An adapter makes a future switch to the Secrets API less invasive.
- Use stable, namespaced keys: plan names such as my-plugin/service-token, without treating the namespace as authorization.
- Model the three read states: distinguish missing, available, and retrieval error.
- Plan import and rotation separately: import removes plaintext from the normal path; rotation reduces the risk of historical copies.
- Review logs and operational tools: avoid logging values, placing tokens in URLs, or passing them as command-line arguments.
- Test in a disposable environment: the feature plugin exists to validate the API before merge. Use it to find incompatibilities, including with hosting providers.
- Keep compatibility fallbacks only as long as needed: if your plugin supports older WordPress versions, encapsulate the fallback and remove it when your support matrix allows.
Timeline and the practical decision for the 7.2 cycle
WordPress 7.2 is currently in alpha. Beta 1 is scheduled for October 20–22 and the final release for December 8–10, 2026. The Secrets API proposal says that before Beta 1 the work should either be merged into Core or explicitly deferred to 7.3 rather than rushed.
For plugin maintainers, the useful action now is to prepare architecture and tests, not to assume availability. The feature plugin provides a concrete target for experimentation, and the proposal already establishes important principles — mandatory encryption, explicit import, no export, and no per-plugin isolation — but the decision that turns this into an official WordPress API still depends on the Core merge process.
