Timothy Jacobs

<p>When a network error is encountered, API clients should be able to retry a request without a risk of their request being processed twice.<br />
WP API Idempotence adds support for clients to include an idempotency key that uniquely identifies that request. If the server detects<br />
that a request with the same key has already been processed or is currently being processed, the response for the initial request will<br />
be returned.</p>
<p>For Example:</p>
<pre><code>{
    "title": "My Important Post",
    "content": "This will only go out once!",
    "status": "draft",
    "idempotency_key": "1ced64e9-9537-4b7b-9919-444d9e15e201"
}
</code></pre>
<h4>Configuration</h4>
<ul>
<li>Idempotency key can either be passed in the request header or the request body.</li>
<li>The idempotency key name can be customized.</li>
<li>Change the HTTP methods the idempotency key is supported for. Defaults to <code>POST</code>, <code>PUT</code>, <code>PATCH</code>.</li>
</ul>
<p>A sample request interface is included to demonstrate the selected configuration.</p>
<h4>Developers</h4>
<p>The plugin includes two actions to modify the dependency injection container (DIC) and insert custom services.</p>
<p>The <code>wp_api_idempotence_initialize_container_builder</code> action allows you to modify the Dependency Injection builder itself and<br />
the <code>wp_api_idempotence_initialize_container</code> action allows you to override dependencies. For example:</p>
<pre><code>add_action( 'wp_api_idempotence_initialize_container', function( $container ) {
    $container->set( '_dataStore', DI\object( 'YourName\CustomDataStore' ) );
} );
</code></pre>
<p>Under the hood, the plugin is made up of a <code>DataStore</code>, <code>RequestHasher</code>, <code>ResponseSerializer</code> and <code>RequestPoller</code>.</p>
<p>The <code>DataStore</code> is primarily responsible for retrieving or storing an idempotent request. By default, requests<br />
are stored in a custom database table. This could be substituted for a custom driver by implementing the <code>DataStore</code><br />
interface. For example a Redis server.</p>
<p>The <code>RequestHasher</code> produces a unique hash for a <code>WP_REST_Request</code> object. This hash is based off of the contents of<br />
the request, not for the object via <code>spl_object_hash</code> or similar. This can also be substituted by implementing the<br />
    RequestHasher interface.</p>
<p>The <code>ResponseSerializer</code> converts a <code>WP_REST_Response</code> or <code>WP_Error</code> object back and forth from a string representation.<br />
The default JSON serializer supports filtering the serialization process using the <code>wp_api_idempotence_serialized_response_data</code><br />
and <code>wp_api_idempotence_attach_serialized_response_data</code> filters. See <code>src/ResponseSerializer/Filtered.php</code>.<br />
The entire serializer can be substituted by implementing the <code>ResponseSerializer</code> interface.</p>
<p>Finally, the <code>RequestPoller</code> class polls the data store for a response if it is determined that an idempotent request<br />
is currently being processed when another request with the same key arrives. By default, the data store is polled<br />
every seconds a maximum of 15 times to try and retrieve a response object. If no response is found, an error with code<br />
    rest_duplicate_idempotency_key will be returned. This can be adjusted by overwriting the <code>poll.sleepSeconds</code> and<br />
    poll.maxQueries in the DIC. The <code>RequestPoller</code> can also be entirely subsituted by implementing the <code>RequestPoller</code><br />
interface.</p>
<h4>Contributing</h4>
<p>This plugin is hosted on <a href="https://github.com/iron-bound-designs/wp-api-idempotence" rel="nofollow ugc">GitHub</a>. Issues and pull requests are welcomed.</p>


WP REST API Idempotent Requests

Allow REST API clients to safely retry requests in case of network errors without risk of the request being processed twice.

George Stephanis

Brandon Kraft

Kaspars

Derek Herman

Arslan Kalwar

<p><strong>⚠️ IMPORTANT: This plugin has been merged into WordPress core version 5.6 and doesn’t have to be installed separately. <a href="https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/" rel="nofollow ugc">View the integration guide <span aria-hidden="true" class="wp-exclude-emoji">→</span></a></strong></p>
<p>Use Application Passwords to authenticate users without providing their passwords directly. Instead, a unique password is generated for each application without revealing the user’s main password. Application passwords can be revoked for each application individually.</p>
<p><strong>Important:</strong> Application Passwords can be used only for authenticating API requests such as <a href="https://developer.wordpress.org/rest-api/" rel="nofollow ugc">REST API</a> and <a href="https://codex.wordpress.org/XML-RPC_WordPress_API" rel="nofollow ugc">XML-RPC</a>, and they won’t work for regular site logins.</p>
<h4>Contribute</h4>
<ul>
<li>Translate the plugin <a href="https://translate.wordpress.org/projects/wp-plugins/application-passwords/" rel="nofollow ugc">into your language</a>.</li>
<li>Report issues, suggest features and contribute code <a href="https://github.com/WordPress/application-passwords" rel="nofollow ugc">on GitHub</a>.</li>
</ul>
<h4>Creating Application Password Manually</h4>
<ol>
<li>Go the User Profile page of the user that you want to generate a new application password for.  To do so, click <em>Users</em> on the left side of the WordPress admin, then click on the user that you want to manage.</li>
<li>Scroll down until you see the Application Passwords section.  This is typically at the bottom of the page.</li>
<li>Within the input field, type in a name for your new application password, then click <em>Add New</em>.<br />
<strong>Note:</strong> The application password name is only used to describe your password for easy management later.  It will not affect your password in any way.  Be descriptive, as it will lead to easier management if you ever need to change it later.</li>
<li>Once the <em>Add New</em> button is clicked, your new application password will appear.  Be sure to keep this somewhere safe, as it will not be displayed to you again.  If you lose this password, it cannot be obtained again.</li>
</ol>
<h4>Two Factor Support</h4>
<p>Application Passwords can be used together with the <a href="https://wordpress.org/plugins/two-factor/" rel="ugc">Two Factor plugin</a> as long as you bypass the API acccess restrictions added by the Two Factor plugin. Those protections disable API requests with password authentication <em>for users with Two Factor enabled</em>.</p>
<p>Use the <code>two_factor_user_api_login_enable</code> filter to allow API requests authenticated using an application passwords:</p>
<pre><code>add_filter( 'two_factor_user_api_login_enable', function( $enable ) {
    // Allow API login when using an application password even with 2fa enabled.
    if ( did_action( 'application_password_did_authenticate' ) ) {
        return true;
    }

    return $enable;
} );
</code></pre>
<p>This is not required if the user associated with the application password doesn’t have any of the Two Factor methods enabled.</p>
<h4>Requesting Password for Application</h4>
<p>To request a password for your application, redirect users to:</p>
<pre><code>https://example.com/wp-admin/admin.php?page=auth_app
</code></pre>
<p>and use the following <code>GET</code> request parameters to specify:</p>
<ul>
<li><code>app_name</code> (required) – The human readable identifier for your app. This will be the name of the generated application password, so structure it like … “WordPress Mobile App on iPhone 12” for uniqueness between multiple versions. If omitted, the user will be required to provide an application name.</li>
<li><code>success_url</code> (recommended) – The URL that you’d like the user to be sent to if they approve the connection. Two GET variables will be appended when they are passed back — <code>user_login</code> and <code>password</code> — these credentials can then be used for API calls. If the <code>success_url</code> variable is omitted, a password will be generated and displayed to the user, to manually enter into your application.</li>
<li><code>reject_url</code> (optional) – If included, the user will get sent there if they reject the connection. If omitted, the user will be sent to the <code>success_url</code>, with <code>?success=false</code> appended to the end. If the <code>success_url</code> is omitted, the user will be sent to their dashboard.</li>
</ul>
<h4>Testing an Application Password</h4>
<p>We use <a href="https://curl.haxx.se" rel="nofollow ugc">curl</a> to send HTTP requests to the API endpoints in the examples below.</p>
<h4>WordPress REST API</h4>
<p>Make a REST API call to update a post. Because you are performing a <code>POST</code> request, you will need to authorize the request using your newly created base64 encoded access token. If authorized correctly, you will see the post title update to “New Title.”</p>
<pre><code>curl --user "USERNAME:APPLICATION_PASSWORD" -X POST -d "title=New Title" https://LOCALHOST/wp-json/wp/v2/posts/POST_ID
</code></pre>
<p>When running this command, be sure to replace <code>USERNAME</code> and <code>APPLICATION_PASSWORD</code> with your credentials (curl takes care of base64 encoding and setting the <code>Authorization</code> header), <code>LOCALHOST</code> with the hostname of your WordPress installation, and <code>POST_ID</code> with the ID of the post that you want to edit.</p>
<h4>XML-RPC</h4>
<p>Unlike the WordPress REST API, XML-RPC does not require your username and password to be base64 encoded. Send an XML-RPC request to list all users:</p>
<pre><code>curl -H 'Content-Type: text/xml' -d '<methodCall><methodName>wp.getUsers</methodName><params><param><value>1</value></param><param><value>USERNAME</value></param><param><value>PASSWORD</value></param></params></methodCall>' https://LOCALHOST/xmlrpc.php
</code></pre>
<p>In the above example, replace <code>USERNAME</code> with your username, <code>PASSWORD</code> with your new application password, and <code>LOCALHOST</code> with the hostname of your WordPress installation. This should output a response containing all users on your site.</p>
<h4>Plugin History</h4>
<p>This is a feature plugin that is a spinoff of the main <a href="https://github.com/WordPress/two-factor/" rel="nofollow ugc">Two-Factor Authentication plugin</a>.</p>


Application Passwords

Straightforward and nicely executed. Thank you for creating this. 

Excellent

This plugin saved me a bunch of time and concern when trying to lock down a couple of scripts. I was initially concerned that I was going to be in for some hoop-jumping to get it set up. But once I jumped in, I had it working in no time.

Simple setup, super handy!

Creates unique passwords for applications to authenticate users without revealing their main passwords.

WP REST API Idempotent Requests vs Application Passwords