Split auth endpoint again

source/includes/wp-api-v1/_authentication-endpoint.md

@@ -0,0 +1,129 @@
+# Authentication Endpoint #
+
+The authentication endpoint can be used by any app to *allow users to generate API keys* for your app. This makes integration with WooCommerce API easier because the user only needs to grant access to your app via a URL. After being redirected back to your app, the API keys will be sent back in a separate POST request.
+
+The following image illustrates how this works:
+
+![Authentication Endpoint flow](images/woocommerce-auth-endpoint-flow.png)
+
+<aside class="warning">
+	This endpoint works exclusively for users to generate API keys and facilitate integration between the WooCommerce REST API and an application. In no way is this endpoint intended to be used as login method for customers.
+</aside>
+
+## URL parameters ##
+
+|   Parameter    |  Type  |                                                                                  Description                                                                                  |
+|----------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `app_name`     | string | Your app name <i class="label label-info">mandatory</i>                                                                                                                       |
+| `scope`        | string | Level of access. Available: `read`, `write` and `read_write` <i class="label label-info">mandatory</i>                                                                        |
+| `user_id`      | string | User ID in your app. For your internal reference, used when the user is redirected back to your app. NOT THE USER ID IN WOOCOMMERCE <i class="label label-info">mandatory</i> |
+| `return_url`   | string | URL the user will be redirected to after authentication <i class="label label-info">mandatory</i>                                                                             |
+| `callback_url` | string | URL that will receive the generated API key. Note: this URL should be over **HTTPS** <i class="label label-info">mandatory</i>                                                |
+
+## Creating an authentication endpoint URL ##
+
+You must use the `/wc-auth/v1/authorize` endpoint and pass the above parameters as a query string.
+
+> Example of how to build an authentication URL:
+
+```shell
+# Bash example
+STORE_URL='http://example.com'
+ENDPOINT='/wc-auth/v1/authorize'
+PARAMS="app_name=My App Name&scope=read_write&user_id=123&return_url=http://app.com/return-page&callback_url=https://app.com/callback-endpoint"
+QUERY_STRING="$(perl -MURI::Escape -e 'print uri_escape($ARGV[0]);' "$PARAMS")"
+QUERY_STRING=$(echo $QUERY_STRING | sed -e "s/%20/\+/g" -e "s/%3D/\=/g" -e "s/%26/\&/g")
+
+echo "$STORE_URL$ENDPOINT?$QUERY_STRING"
+```
+
+```javascript
+var querystring = require('querystring');
+
+var store_url = 'http://example.com';
+var endpoint = '/wc-auth/v1/authorize';
+var params = {
+  app_name: 'My App Name',
+  scope: 'read_write',
+  user_id: 123,
+  return_url: 'http://app.com/return-page',
+  callback_url: 'https://app.com/callback-endpoint'
+};
+var query_string = querystring.stringify(params).replace(/%20/g, '+');
+
+console.log(store_url + endpoint + '?' + query_string);
+```
+
+```php
+<?php
+$store_url = 'http://example.com';
+$endpoint = '/wc-auth/v1/authorize';
+$params = [
+    'app_name' => 'My App Name',
+    'scope' => 'write',
+    'user_id' => 123,
+    'return_url' => 'http://app.com',
+    'callback_url' => 'https://app.com'
+];
+$query_string = http_build_query( $params );
+
+echo $store_url . $endpoint . '?' . $query_string;
+?>
+```
+
+```python
+from urllib.parse import urlencode
+
+store_url = 'http://example.com'
+endpoint = '/wc-auth/v1/authorize'
+params = {
+    "app_name": "My App Name",
+    "scope": "read_write",
+    "user_id": 123,
+    "return_url": "http://app.com/return-page",
+    "callback_url": "https://app.com/callback-endpoint"
+}
+query_string = urlencode(params)
+
+print("%s%s?%s" % (store_url, endpoint, query_string))
+```
+
+```ruby
+require "uri"
+
+store_url = 'http://example.com'
+endpoint = '/wc-auth/v1/authorize'
+params = {
+  app_name: "My App Name",
+  scope: "read_write",
+  user_id: 123,
+  return_url: "http://app.com/return-page",
+  callback_url: "https://app.com/callback-endpoint"
+}
+query_string = URI.encode_www_form(params)
+
+puts "#{store_url}#{endpoint}?#{query_string}"
+```
+
+> Example of JSON posted with the API Keys
+
+```
+{
+    "key_id": 1,
+    "user_id": 123,
+    "consumer_key": "ck_xxxxxxxxxxxxxxxx",
+    "consumer_secret": "cs_xxxxxxxxxxxxxxxx",
+    "key_permissions": "read_write"
+}
+```
+
+Example of the screen that the user will see:
+
+![Authentication Endpoint example](images/woocommerce-auth-endpoint-example.png)
+
+## Notes ##
+
+- While redirecting the user using `return_url`, you are also sent `success` and `user_id` parameters as query strings.
+- `success` sends `0` if the user denied, or `1` if authenticated successfully.
+- Use `user_id` to identify the user when redirected back to the (`return_url`) and also remember to save the API Keys when your `callback_url` is posted to after auth.
+- The auth endpoint will send the API Keys in JSON format to the `callback_url`, so it's important to remember that some languages such as PHP will not display it inside the `$_POST` global variable, in PHP you can access it using `$HTTP_RAW_POST_DATA` (for old PHP versions) or `file_get_contents('php://input');`.

source/includes/wp-api-v1/_authentication.md

@@ -96,134 +96,4 @@ If you are having trouble generating a correct signature, you'll want to review
 * You may test your generated signature using LinkedIn's [OAuth test console](http://developer.linkedinlabs.com/oauth-test/) -- leave the member token/secret blank.
 * Twitter has great instructions on [generating signatures](https://dev.twitter.com/docs/auth/creating-signature) with OAuth 1.0a, but remember tokens are not used with this implementation.
 * Note that the request body is *not* signed as per the OAuth spec, see [Google's OAuth 1.0 extension](https://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html) for details on why.
-* If including filter fields in your request, it saves a lot of trouble if you can order your filter fields alphabetically before submitting. Many Oauth libraries won't order subquery fields properly, resulting in invalid signatures.
-
-## Application authentication ##
-
-The authentication endpoint can be used by any app to *allow users to generate API keys* for your app. This makes integration with WooCommerce API easier because the user only needs to grant access to your app via a URL. After being redirected back to your app, the API keys will be sent back in a separate POST request.
-
-The following image illustrates how this works:
-
-![Authentication Endpoint flow](images/woocommerce-auth-endpoint-flow.png)
-
-<aside class="warning">
-	This endpoint works exclusively for users to generate API keys and facilitate integration between the WooCommerce REST API and an application. In no way is this endpoint intended to be used as login method for customers.
-</aside>
-
-### URL parameters ###
-
-|   Parameter    |  Type  |                                                                                  Description                                                                                  |
-|----------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `app_name`     | string | Your app name <i class="label label-info">mandatory</i>                                                                                                                       |
-| `scope`        | string | Level of access. Available: `read`, `write` and `read_write` <i class="label label-info">mandatory</i>                                                                        |
-| `user_id`      | string | User ID in your app. For your internal reference, used when the user is redirected back to your app. NOT THE USER ID IN WOOCOMMERCE <i class="label label-info">mandatory</i> |
-| `return_url`   | string | URL the user will be redirected to after authentication <i class="label label-info">mandatory</i>                                                                             |
-| `callback_url` | string | URL that will receive the generated API key. Note: this URL should be over **HTTPS** <i class="label label-info">mandatory</i>                                                |
-
-### Creating an authentication endpoint URL ###
-
-You must use the `/wc-auth/v1/authorize` endpoint and pass the above parameters as a query string.
-
-> Example of how to build an authentication URL:
-
-```shell
-# Bash example
-STORE_URL='http://example.com'
-ENDPOINT='/wc-auth/v1/authorize'
-PARAMS="app_name=My App Name&scope=read_write&user_id=123&return_url=http://app.com/return-page&callback_url=https://app.com/callback-endpoint"
-QUERY_STRING="$(perl -MURI::Escape -e 'print uri_escape($ARGV[0]);' "$PARAMS")"
-QUERY_STRING=$(echo $QUERY_STRING | sed -e "s/%20/\+/g" -e "s/%3D/\=/g" -e "s/%26/\&/g")
-
-echo "$STORE_URL$ENDPOINT?$QUERY_STRING"
-```
-
-```javascript
-var querystring = require('querystring');
-
-var store_url = 'http://example.com';
-var endpoint = '/wc-auth/v1/authorize';
-var params = {
-  app_name: 'My App Name',
-  scope: 'read_write',
-  user_id: 123,
-  return_url: 'http://app.com/return-page',
-  callback_url: 'https://app.com/callback-endpoint'
-};
-var query_string = querystring.stringify(params).replace(/%20/g, '+');
-
-console.log(store_url + endpoint + '?' + query_string);
-```
-
-```php
-<?php
-$store_url = 'http://example.com';
-$endpoint = '/wc-auth/v1/authorize';
-$params = [
-    'app_name' => 'My App Name',
-    'scope' => 'write',
-    'user_id' => 123,
-    'return_url' => 'http://app.com',
-    'callback_url' => 'https://app.com'
-];
-$query_string = http_build_query( $params );
-
-echo $store_url . $endpoint . '?' . $query_string;
-?>
-```
-
-```python
-from urllib.parse import urlencode
-
-store_url = 'http://example.com'
-endpoint = '/wc-auth/v1/authorize'
-params = {
-    "app_name": "My App Name",
-    "scope": "read_write",
-    "user_id": 123,
-    "return_url": "http://app.com/return-page",
-    "callback_url": "https://app.com/callback-endpoint"
-}
-query_string = urlencode(params)
-
-print("%s%s?%s" % (store_url, endpoint, query_string))
-```
-
-```ruby
-require "uri"
-
-store_url = 'http://example.com'
-endpoint = '/wc-auth/v1/authorize'
-params = {
-  app_name: "My App Name",
-  scope: "read_write",
-  user_id: 123,
-  return_url: "http://app.com/return-page",
-  callback_url: "https://app.com/callback-endpoint"
-}
-query_string = URI.encode_www_form(params)
-
-puts "#{store_url}#{endpoint}?#{query_string}"
-```
-
-> Example of JSON posted with the API Keys
-
-```
-{
-    "key_id": 1,
-    "user_id": 123,
-    "consumer_key": "ck_xxxxxxxxxxxxxxxx",
-    "consumer_secret": "cs_xxxxxxxxxxxxxxxx",
-    "key_permissions": "read_write"
-}
-```
-
-Example of the screen that the user will see:
-
-![Authentication Endpoint example](images/woocommerce-auth-endpoint-example.png)
-
-### Notes ###
-
-- While redirecting the user using `return_url`, you are also sent `success` and `user_id` parameters as query strings.
-- `success` sends `0` if the user denied, or `1` if authenticated successfully.
-- Use `user_id` to identify the user when redirected back to the (`return_url`) and also remember to save the API Keys when your `callback_url` is posted to after auth.
-- The auth endpoint will send the API Keys in JSON format to the `callback_url`, so it's important to remember that some languages such as PHP will not display it inside the `$_POST` global variable, in PHP you can access it using `$HTTP_RAW_POST_DATA` (for old PHP versions) or `file_get_contents('php://input');`.
+* If including filter fields in your request, it saves a lot of trouble if you can order your filter fields alphabetically before submitting. Many Oauth libraries won't order subquery fields properly, resulting in invalid signatures.

source/index.md

@@ -35,6 +35,7 @@ includes:
   - wp-api-v1/taxes
   - wp-api-v1/tax-classes
   - wp-api-v1/webhooks
+  - wp-api-v1/authentication-endpoint
 
 search: false
 ---