WP REST API Application Registry

Information for Application Developers

The broker authentication system is designed to be simple to implement for client applications, with most of the complexity hidden inside the broker itself. The process involves a short OAuth flow with the broker before using the normal OAuth flow with the site.

How to connect

Before connecting, you need to create an application. This requires the callback URI to be used during the OAuth authorisation flow with the site you’re connecting to. Once your application is created, note your client key and secret. These are required to communicate with the broker.

From the application’s perspective, a single HTTP request is required. This is a POST request to the Initialization Endpoint, which is http://broker.local/broker/connect/ – this is called the Broker Connection Request.

The Broker Connection Request requires a single parameter: server_url. This should be the URL for the WordPress site the application wishes to connect to. (This must be passed in the POST body as application/x-www-form-urlencoded data.)

This request must be authenticated via OAuth 1.0a with a request signature. The signature should be generated using the tokenless signature process using the HMAC-SHA1 method; this is the same way you sign requests to the Request Token endpoint on a site. Your client key and secret are those from the broker.

The application sends this request, then waits for a response. The broker synchronously handles the broker process, which may take up to 30 seconds. Your application should wait at least 30 seconds before treating the process as timed-out.

Once the broker has received a response back from the server, the credentials will be passed back to the application as JSON-encoded data, with the client_token and client_secret keys containing the token key and secret respectively. These can then be used as the application key (oauth_consumer_key) and secret directly with the site, without needing broker interaction again.

The broker response also returns the api_root key for your convenience; this is the root API URL as discovered by autodiscovery. The broker runs the autodiscovery process internally anyway, so this allows you to avoid excess requests to the site.

Repeated calls to the broker will return the same key and secret (this is de-duplicated by the site).

Example broker flow

Alice has created an application which uses the WordPress REST API, and is now ready to distribute it. Firstly, she creates a new application here, and enters the details. After creating the app, she notes down her OAuth credentials: the client key is testkey and the client secret is test secret. She adds these into her app.

Bob opens Alice’s application, and enters his site URL: http://example.com/ – He then presses the “Connect” button.

The application then builds the request data. Firstly, it prepares the POST body to be sent, which has the server_url parameter set to http://example.com/, which is then encoded into data. The body data is thus:

server_url=http%3A%2F%2Fexample.com%2F

The application then builds the signature. The parameters are normalised and the signature base string is built. The request is a POST request to http://broker.local/broker/connect/, so the signature base string is:

POST&http%3A%2F%2Fbroker.local%2Fbroker%2Fconnect%2F&request_url%3Dhttp%253A%252F%252Fexample.com%252

The application then builds the signature key. This is the client secret and the token secret encoded, then concatenated with an &. As we do not have a token secret, this is simply the client secret encoded and suffixed with an &, so the signature key is:

test%20secret&

The signature is then created and passed in the Authorization header with the request. The full request is:

POST http://broker.local/broker/connect/
Authorization: OAuth ...

server_url=http%3A%2F%2Fexample.com%2F

The broker then begins the broker process, and eventually passes the client key and secret back to the application. The response is:

{"client_key": "appkey", "client_secret": "appsecret"}

The application then uses these to start the authorisation flow directly with the site.