Skip to content

Commit 526fdbf

Browse files
claudiosanchesclaudiosanches
committed
Merge pull request #24 from woothemes/2.5
2.5 API docs
2 parents 64a15c3 + 6bae8aa commit 526fdbf

21 files changed

+7565
-1733
lines changed

‎source/includes/v3/_authentication-endpoint.md

+88-24
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,111 @@
11
# Authentication Endpoint #
22

3-
Staring in WooCommerce 2.4 we introduced our Authentication Endpoint, where any app can easy allow users to generate API keys and send back automatically to the app.
4-
5-
This makes integration with WooCommerce API much simpler, since the user only needs to access a URL, click in the "accept" button and will be redirected back to the app and the API keys are sent back in a POST request.
3+
Starting in WooCommerce 2.4 we introduced an Authentication Endpoint, This can be used by any app to allow users to generate API keys. This makes integration with WooCommerce API simpler because the user only needs to access a URL and click "accept". After being redirected back to the app, the API keys will be sent in a POST request.
64

75
The following image illustrates how it's done:
86

97
![Authentication Endpoint flow](images/woocommerce-auth-endpoint-flow.png)
108

119
<aside class="warning">
12-
Note that 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 proposes to be used as login method for customers.
10+
Note that 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 proposed to be used as login method for customers.
1311
</aside>
1412

1513
## URL parameters ##
1614

17-
| Paramenter | Type | Description |
15+
| Parameter | Type | Description |
1816
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1917
| `app_name` | string | Your app name <i class="label label-info">mandatory</i> |
2018
| `scope` | string | Level of access. Available: `read`, `write` and `read_write` <i class="label label-info">mandatory</i> |
2119
| `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> |
22-
| `return_url` | string | URL that will be used for receive the user back in your app <i class="label label-info">mandatory</i> |
23-
| `callback_url` | string | URL that will receive the generated API key. Important to note that this URL should be over **SSL** <i class="label label-info">mandatory</i> |
20+
| `return_url` | string | URL the user will be redirected to after authentication <i class="label label-info">mandatory</i> |
21+
| `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> |
2422

2523
## Creating Authentication Endpoint URL ##
2624

27-
You must use the `/wc-auth/v1/authorize` endpoint and pass the above parameters as query string.
25+
You must use the `/wc-auth/v1/authorize` endpoint and pass the above parameters as a query string.
26+
27+
> Example of how to build an authentication URL:
2828
29-
> Example of how do it in PHP:
29+
```shell
30+
# Bash example
31+
STORE_URL='http://example.com'
32+
ENDPOINT='/wc-auth/v1/authorize'
33+
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"
34+
QUERY_STRING="$(perl -MURI::Escape -e 'print uri_escape($ARGV[0]);' "$PARAMS")"
35+
QUERY_STRING=$(echo $QUERY_STRING | sed -e "s/%20/\+/g" -e "s/%3D/\=/g" -e "s/%26/\&/g")
36+
37+
echo "$STORE_URL$ENDPOINT?$QUERY_STRING"
38+
```
3039

40+
```javascript
41+
var querystring = require('querystring');
42+
43+
var store_url = 'http://example.com';
44+
var endpoint = '/wc-auth/v1/authorize';
45+
var params = {
46+
app_name: 'My App Name',
47+
scope: 'read_write',
48+
user_id: 123,
49+
return_url: 'http://app.com/return-page',
50+
callback_url: 'https://app.com/callback-endpoint'
51+
};
52+
var query_string = querystring.stringify(params).replace(/%20/g, '+');
53+
54+
console.log(store_url + endpoint + '?' + query_string);
3155
```
56+
57+
```php
58+
<?php
3259
$store_url = 'http://example.com';
33-
$endpoint = '/wc-auth/v1/authorize';
34-
$params = array(
35-
'app_name' => 'My App Name',
36-
'scope' => 'read_write',
37-
'user_id' => 123,
38-
'return_url' => 'http://app.com/return-page',
39-
'callback_url' => 'https://app.com/callback-endpoint'
40-
);
41-
echo $store_url . $endpoint . '?' . http_build_query( $params );
60+
$endpoint = '/wc-auth/v1/authorize';
61+
$params = [
62+
'app_name' => 'My App Name',
63+
'scope' => 'write',
64+
'user_id' => 123,
65+
'return_url' => 'http://app.com',
66+
'callback_url' => 'https://app.com'
67+
];
68+
$query_string = http_build_query( $params );
69+
70+
echo $store_url . $endpoint . '?' . $query_string;
71+
?>
72+
```
73+
74+
```python
75+
from urllib.parse import urlencode
76+
77+
store_url = 'http://example.com'
78+
endpoint = '/wc-auth/v1/authorize'
79+
params = {
80+
"app_name": "My App Name",
81+
"scope": "read_write",
82+
"user_id": 123,
83+
"return_url": "http://app.com/return-page",
84+
"callback_url": "https://app.com/callback-endpoint"
85+
}
86+
query_string = urlencode(params)
87+
88+
print("%s%s?%s" % (store_url, endpoint, query_string))
89+
```
90+
91+
```ruby
92+
require "uri"
93+
94+
store_url = 'http://example.com'
95+
endpoint = '/wc-auth/v1/authorize'
96+
params = {
97+
app_name: "My App Name",
98+
scope: "read_write",
99+
user_id: 123,
100+
return_url: "http://app.com/return-page",
101+
callback_url: "https://app.com/callback-endpoint"
102+
}
103+
query_string = URI.encode_www_form(params)
104+
105+
puts "#{store_url}#{endpoint}?#{query_string}"
42106
```
43107

44-
> Example the JSON posted with the API Keys
108+
> Example of JSON posted with the API Keys
45109
46110
```
47111
{
@@ -53,14 +117,14 @@ echo $store_url . $endpoint . '?' . http_build_query( $params );
53117
}
54118
```
55119

56-
Example of the screen that the user will access:
120+
Example of the screen that the user will see:
57121

58122
![Authentication Endpoint example](images/woocommerce-auth-endpoint-example.png)
59123

60124
## Notes and Tips ##
61125

62-
- While redirecting the user using `return_url` are also sent `success` and `user_id` parameters as query strings.
63-
- `success` sends `0` if the user denied or `1` if authenticated successfully.
64-
- Use `user_id` to identify the user when redirected back (`return_url`) to your app and also to save the API Keys in your `callback_url`.
65-
- This 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');`.
126+
- While redirecting the user using `return_url`, you are also sent `success` and `user_id` parameters as query strings.
127+
- `success` sends `0` if the user denied, or `1` if authenticated successfully.
128+
- 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.
129+
- 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');`.
66130
- This authentication endpoint is used only to make easy integration with WooCommerce REST API. THIS NOT INTENDED TO BE USED AS A LOGIN ENDPOINT FOR CUSTOMERS!

0 commit comments

Comments
 (0)