WordPress REST Auth Token.
Lightweight SDK to implement oAuth2 authentication system for WordPress REST API.
Table of contents
- Easy to learn, easy to use
- Opensource
- Forever free
- Lightweight (Less than 10kb)
- No dependency
- Supports CORS
- Full customizable
Open your bash/terminal and run the command
composer require wrat/wrat
Open you terminal in targeted directory and run the commans
git clone https://github.com/imjafran/wrat.git ./
Manual installation
- Download as zip
- Extract into your project directory
- Require
wrat.php
file
Initializing WRAT
<?php
# require using composer
require __DIR__ . "/vendor/autoload.php";
# or require directly
require_once __DIR__ . "/path/to/wrat.php";
# Initializing WRAT
WRAT::init();
WRAT has two endpoints to handle authentication stuffs. Once you install WRAT, these endpoints will be registered automatically.
Authenticates email/username and password pair from request payload and returns access token for further usages.
Endpoint
/wp-json/wrat/token
Method : POST
Request payload
{
"email" : "user@email.com",
"password" : "12345",
}
or using username instead
{
"username" : "your-username",
"password" : "12345",
}
Response body
Success
{
"success": true,
"user": {
"id": 21,
"first_name": "Test",
"last_name": "User",
"email": "test@gmail.com",
"role": "customer",
"token": "ACCESS_TOKEN_HERE"
}
}
Failed
{
"success": false,
"code": "ERROR_CODE_HERE"
}
- See List of error codes for error references
- See Refresh Token to refresh the token
Verifies requested token, if its working
Endpoint
/wp-json/wrat/verify
Method : POST
Request payload
{
"wrat" : "TOKEN_HERE"
}
Response body
Same as before. See auth section
NOTE: Here, only JSON payload has been showns as example, but all available methods of server requests work with WRAT.
From you REST client, you can pass WRAT token as bearer token
, request payload
, query parameter
and obviously as json
to authenticate current user.
Bearer token
curl https://your-wordpress-site.com/wp-json
-H "Accept: application/json"
-H "Authorization: Bearer {TOKEN_HERE}"
alternatively, custom authorization
curl https://your-wordpress-site.com/wp-json
-H "Accept: application/json"
-H "Authorization: WRAT {TOKEN_HERE}"
URL query parameter
https://your-wordpress-site.com/wp-json/your/route/?wrat=TOKEN_HERE
Request payload
{
"some" : "data",
"wrat" : "TOKEN_HERE"
}
A valid token will make sure that the server knowns your identity in REST operation. Simply, this will occur is_user_logged_in() // true
over whole REST API of that website.
Refreshing token will create new token pair forcefully, otherwise returns existing token if found and created new only no token found.
{
"email" : "user@email.com",
"password" : "12345",
"refresh" : true
}
- invalid_wrat - The provided token is incorrect.
- invalid_email - The email is either empty or invalid or incorrect.
- incorrect_username - The username is either empty or wrong, works if no email parameter found.
- incorrect_password - The provided password is incorrect.
wrat_before_auth
Executed before comparing email/email and password pair.
Example
function wrat_before_auth_callback(){
/**
* do whatever you want
**/
}
add_action('wrat_before_auth', 'wrat_before_auth_callback', 12, 0);
wrat_after_auth
Executed after authenticated successfully.
Example
function wrat_after_auth_callback( $user_id ){
/**
* @user_id Integer
* */
}
add_action('wrat_after_auth', 'wrat_after_auth_callback', 12, 1);
wrat_auth_failed
Executed after authentication failed.
Example
function wrat_auth_failed_callback( $email, $username, $errors ){
/**
* @email String
* @username String
* @errors Array
* */
}
add_action('wrat_auth_failed', 'wrat_auth_failed_callback', 12, 3);
wrat_cors
Enabling CORS will let In-Browser-JavaScript work with your REST API. By default, it's enabled to all request origins. You may customize the CORS urls.
Example
/**
* @urls String
*
* Default : "*"
* */
function wrat_cors_callback( $urls = '*' ){
return $urls;
}
add_filter('wrat_cors', 'wrat_cors_callback');
wrat_endpoints
The endpoints you define will act exactly opposite of rest of the endpoints.
Example
/**
* @endpoints Array
*
* Default : []
* */
function wrat_endpoints_callback( $endpoints = [] ){
$endpoints[] = 'some/endpoints/*';
$endpoints[] = 'another/endpoint';
return $endpoints;
}
add_filter('wrat_endpoints', 'wrat_endpoints_callback');
wrat_blacklist_endpoints
There are two modes.
Whitelisting
Blacklisting
If wrat_blacklist_endpoints is true
, only wrat filtered endpoints will require authentication, rest of the endpoints will be open.
Example
/**
* @enabled Boolean
*
* Default : true
* */
function wrat_blacklist_endpoints_callback( $enabled = true ){
return $enabled;
}
add_filter('wrat_blacklist_endpoints', 'wrat_blacklist_endpoints_callback');
wrat_endpoint_prefix
Add the extended url prefix if your WordPress site in installed in a sub directory.
If your site is like this
yoursite.com/staging/wp-json/wrat/token
staging
is your endpoint prefix. Add this as wrat_endpoint_prefix
Example
/**
* @endpoints String
*
* Default : ""
* */
function wrat_endpoint_prefix_callback( $prefix = '' ){
return $endpoints;
}
add_filter('wrat_endpoint_prefix', 'wrat_endpoint_prefix_callback');
wrat_user_data
Userdata object returns after authentication
Example
function wrat_user_data_callback( $data ){
/**
* @data Object
* */
return $data;
}
add_filter('wrat_user_data', 'wrat_user_data_callback');
wrat_get_token
Returns user's access token from user id
Example
$token = wrat_get_token(int $user_id);
# returns string token
wrat_get_user
Returns user data including access token from user id
Example
$user = wrat_get_user(int $user_id);
# or
$user = wrat_get_user(WP_User $user);
# returns object data
Publisher Jafran Hasan
Contributors
Wanna see your name in the list? Git Repository
Pulling requests are welcome but please open a ticket before pushing to discus on what you would like to extend.