json-api-auth / readme.txt

readme.txt in JSON API Auth 3.1.0, at readme.txt

152 lines 5.2 KB

Raw Download Zip

1	=== JSON API Auth ===
2
3	Donate link: http://www.parorrey.com
4	Tags: json api, api, authenticate user, WordPress user authentication
5	Contributors: parorrey
6	Stable tag: 3.1.0
7	Requires at least: 3.0.1
8	Tested up to: 7.0
9	Requires PHP: 7.4
10	License: GPLv2 or later
11
12	License URI: http://www.gnu.org/licenses/gpl-2.0.html
13
14	Extends the JSON API Plugin for RESTful user authentication
15
16	== Description ==
17
18	JSON API Auth extends the JSON API Plugin to allow RESTful user authentication.
19
20	JSON API Plugin, that is required, was closed on August 7, 2019 from WordPress repository. You can download <a href="https://github.com/PI-Media/json-api">JSON API Plugin</a> from https://github.com/PI-Media/json-api until it is republished and available on WordPress.
21
22	Features include:
23
24	* Generate Auth Cookie for user authentication
25
26	* Validate Auth Cookie
27
28	* Get Current User Info
29
30	For documentation: See 'Other Notes' tab above for usage examples.
31
32	Credits: http://www.parorrey.com/solutions/json-api-auth/
33
34	== Installation ==
35
36	First you have to install the JSON API for WordPress Plugin (http://wordpress.org/extend/plugins/json-api/installation/). or You can download <a href="https://github.com/PI-Media/json-api">JSON API Plugin</a> from https://github.com/PI-Media/json-api
37
38	To install JSON API Auth just follow these steps:
39
40	* upload the folder "json-api-auth" to your WordPress plugin folder (/wp-content/plugins)
41
42	* activate the plugin through the 'Plugins' menu in WordPress or by using the link provided by the plugin installer
43
44	* activate the controller through the JSON API menu found in the WordPress admin center (Settings -> JSON API)
45
46	== Screenshots ==
47
48	1. Call to generate_auth_cookie endpoint using Postman
49	2. Call to get_currentuserinfo endpoint using Postman
50	3. Call to validate_auth_cookie endpoint using Postman
51
52	== Changelog ==
53
54	= 3.1.0 =
55	* Tested and confirmed working with WordPress 7.0
56	* Bumped minimum PHP requirement to 7.4
57	* Replaced deprecated `wp_capabilities` user meta key with `$user->roles` for reliable role retrieval
58	* Switched avatar retrieval to `get_avatar_url()` (WP 4.2+) with regex fallback, fixing broken avatar URLs in modern WordPress
59	* Added `sanitize_text_field()` to POST parameter handling for improved input security
60	* Fixed `isset()` check on `json_api->query->cookie` in cookie auth hook to avoid PHP notices
61
62	= 3.0.0 =
63	* Updated for WordPress version 6.8
64
65	= 2.9.1 =
66	* Fixed a bug for generate_auth_cookie, get_currentuserinfo endpoints for avatar
67	* Updated for WordPress version 6.4.1
68
69	= 2.9.0 =
70	* Updated for WordPress version 6.1.1
71
72	= 2.8.0 =
73	* Updated for WordPress version 6.0.1
74
75	= 2.7.1 =
76	* Updated for WordPress version 5.9
77
78	= 2.7.0 =
79	* Updated for wordpress version 5.8
80
81	= 2.6.0 =
82	* Updated for wordpress version 5.7
83
84	= 2.5.0 =
85	* Updated for wordpress version 5.5.3
86
87	= 2.4.0 =
88
89	* Fixed bug in the generate_auth_cookie endpoint.
90
91	= 2.3.0 =
92
93	* Updated for JSON API Plugin diretory check error and updated action links.
94
95	= 2.2.0 =
96
97	* Updated for GitHub and settings action links.
98
99	= 2.1.0 =
100
101	* Updated for WordPress version & added JSON API plugin GitHub link due its closing down on WordPress repository.
102
103	= 2.0.0 =
104
105	* Updated for wordpress version
106
107
108	== Frequently Asked Questions ==
109
110	Thanks to 'mattberg' who wrote the auth controller (https://github.com/mattberg/wp-json-api-auth) initially. I have added few methods and authored it as a WordPress plugin so that it could easily be searched and installed vis WordPress.
111
112	* There are following methods available: validate_auth_cookie, generate_auth_cookie, clear_auth_cookie, get_currentuserinfo
113
114	* nonce can be created by calling http://localhost/api/get_nonce/?controller=auth&method=generate_auth_cookie
115
116	* You can then use 'nonce' value to generate cookie. http://localhost/api/auth/generate_auth_cookie/?nonce=f4320f4a67&username=Catherine&password=password-here
117
118	* Use cookie like this with your other controller calls: http://localhost/api/contoller-name/method-name/?cookie=Catherine\|1392018917\|3ad7b9f1c5c2cccb569c8a82119ca4fd
119
120	For instance, you have a new controller 'events' and want to allow users to post new 'event' using 'add_event' method.
121	This is how you will call the end point with cookie and post the event with user info:
122
123	http://localhost/api/events/add_event/?cookie=Catherine\|1392018917\|3ad7b9f1c5c2cccb569c8a82119ca4fd
124
125	If you want sample code how it can be done, check 'JSON API User' plugin https://wordpress.org/plugins/json-api-user/. This Auth plugin is part of JSON API User plugin.
126
127	= Method: validate_auth_cookie =
128
129	It needs 'cookie' var.
130
131	http://localhost/api/auth/validate_auth_cookie/?cookie=Catherine\|1392018917\|3ad7b9f1c5c2cccb569c8a82119ca4fd
132
133
134	= Method: generate_auth_cookie =
135
136	It needs `username`, `password` vars. `seconds` is optional.
137
138	Then generate cookie: http://localhost/api/auth/generate_auth_cookie/?username=john&password=PASSWORD-HERE
139
140	Optional 'seconds' var. It provided, generated cookie will be valid for that many seconds, otherwise default is for 14 days.
141
142	generate cookie for 1 minute: http://localhost/api/auth/generate_auth_cookie/?username=john&password=PASSWORD-HERE&seconds=60
143
144	60 means 1 minute.
145
146
147	= Method: get_currentuserinfo =
148
149	It needs 'cookie' var.
150
151	http://localhost/api/auth/get_currentuserinfo/?cookie=Catherine\|1392018917\|3ad7b9f1c5c2cccb569c8a82119ca4fd
152