{"id":125732,"date":"2026-08-25T21:17:36","date_gmt":"2026-08-25T21:17:36","guid":{"rendered":"https:\/\/make.wordpress.org\/core\/?p=125732"},"modified":"2026-08-25T21:17:37","modified_gmt":"2026-08-25T21:17:37","slug":"proposal-a-secrets-api-for-wordpress-7-2","status":"publish","type":"post","link":"https:\/\/make.wordpress.org\/core\/2026\/08\/25\/proposal-a-secrets-api-for-wordpress-7-2\/","title":{"rendered":"Proposal: A Secrets API for WordPress 7.2"},"content":{"rendered":"

WordPress has no first-class way to store a credential. This proposal outlines a Secrets APIAPI<\/span> An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.<\/span><\/span><\/span> for 7.2, along with WP-CLIWP-CLI<\/span> WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http:\/\/wp-cli.org\/<\/a> https:\/\/make.wordpress.org\/cli\/<\/a><\/span><\/span><\/span> support for it, and explains why the accompanying UIUI<\/span> User interface<\/span><\/span><\/span> should wait for 7.3.<\/p>\n\n\n\n

Why it matters<\/h3>\n\n\n\n

Every pluginPlugin<\/span> A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https:\/\/wordpress.org\/plugins\/<\/a> or can be cost-based plugin from a third-party.<\/span><\/span><\/span> that needs an API key today writes it to the options table in plaintext. That is the only available path, so this isn\u2019t a criticism of plugin authors. The consequence is that credentials end up in the same table as the site tagline, and therefore in every database dump, every backup, every staging clone, and every wp option get<\/code> in a shared terminal.<\/p>\n\n\n\n

Plugins have been solving this independently for years, each with its own key derivation, its own cipher choice, and its own failure modes. Site Kit encrypts its Google credentials. WooCommerce gateways handle payment keys. SMTP plugins hold mail credentials. Each one is a separate audit surface, and none of them can be reviewed once on behalf of the ecosystem.<\/p>\n\n\n\n

This was survivable when the average site held a Mailchimp key and a reCAPTCHA secret. AI service integrations have made credentials both more numerous and far more expensive to lose: a leaked model-provider key is a metered spend liability. The blast radius increased while the storage mechanism stayed the same.<\/p>\n\n\n\n

A second gap is that site owners and hosts increasingly need to answer basic operational questions \u2014 which credentials exist on this site, what code is using them, when were they last rotated. None of those are answerable today, because there is no object to ask about. A credential is just a row in a key-value store.<\/p>\n\n\n\n

CoreCore<\/span> Core is the set of software required to run WordPress. The Core Development Team builds WordPress.<\/span><\/span><\/span> has no concept of a secret; there\u2019s nothing for either problem to attach to.<\/p>\n\n\n\n

Clarifying priorities<\/h3>\n\n\n\n

A tightly-scoped, stable API landed in 7.2 helps push forward on requirements like those documented in the Security Audit for the Connectors screen<\/a>.<\/p>\n\n\n\n

No new UI in 7.2.<\/strong> The storage and retrieval semantics are the part that must be right the first time, because every plugin, every CLICLI<\/span> Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress.<\/span><\/span><\/span> command, and every future adminadmin<\/span> (and super admin)<\/span><\/span><\/span> screen inherits them. A settings screen can be designed properly in 7.3 once there\u2019s a stable API to build against and real usage to design from. The hooksHooks<\/span> In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same.<\/span><\/span><\/span> and accessors an admin screen would need are in scope now; the screen itself is not.<\/p>\n\n\n\n

WP-CLI is in scope.<\/strong> It gives the API a first-party consumer inside the same release, which is the most reliable way to discover whether the surface is actually usable before it freezes. It also closes a real leak of its own: commands that accept credentials as arguments expose them in shell history and in the process list on shared hosts. Reading and writing through the API fixes that in the same change.<\/p>\n\n\n\n

A feature pluginFeature Plugin<\/span> A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins<\/a><\/span><\/span><\/span> ships before the core patchpatch<\/span> A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff<\/strong>. A patch can be applied<\/em> to a codebase for testing.<\/span><\/span><\/span>.<\/strong> Rather than propose an API and ask people to evaluate it from a design document, I\u2019ll publish the implementation as a plugin first. This will let contributors run the API instead of reading about it, expose the awkward parts of the surface while they\u2019re still inexpensive to change, and give sites on 7.0 and 7.1 something usable immediately rather than waiting for December. The core patch then follows with an API surface identical to the plugin\u2019s; nothing anyone builds against it needs rewriting.<\/p>\n\n\n\n

The plugin will prove out the API before we consolidate things into core.<\/p>\n\n\n\n

Proposed API<\/h3>\n\n\n\n

A small function set, a value object, and always-on encryption.<\/p>\n\n\n

\nwp_set_secret( string $name, string $value ): bool|WP_Error\nwp_get_secret( string $name, string $version = WP_Secret_Version::CURRENT ): WP_Secret|null|WP_Error\nwp_delete_secret( string $name ): bool|WP_Error\nwp_import_option_as_secret( string $option, string $name ): bool|WP_Error\n\nWP_Secret::reveal(): string\nWP_Secret::fingerprint(): string\n<\/pre><\/div>\n\n\n
At a call site:<\/p>\n\n\n
\nwp_set_secret( 'my-plugin\/api-key', $key_from_form );\n\n$secret = wp_get_secret( 'my-plugin\/api-key' );\n\nif ( is_wp_error( $secret ) ) {\n    \/\/ Exists, but unusable. Key material changed. Tell the user.\n} elseif ( null === $secret ) {\n    \/\/ Doesn't exist. Show the connect flow.\n} else {\n    $client = new API_Client( $secret->reveal() );\n}\n<\/pre><\/div>\n\n\n
Supporting surface:<\/p>\n\n\n\n