WordPress REST Auth Token.

Lightweight SDK to implement oAuth2 authentication system for WordPress REST API.

Table of contents

• Features
• Install
• Usages
  • Access token
  • Verify
  • Authentication
  • Refresh token
• List of Error Codes
• Customization
  • Action hooks
  • Filter hooks
  • Functions
• Contribution

Features

• Easy to learn, easy to use
• Opensource
• Forever free
• Lightweight (Less than 10kb)
• No dependency
• Supports CORS
• Full customizable

Install

Using composer

Open your bash/terminal and run the command

composer require wrat/wrat

Clone from Git

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();

Usages

WRAT has two endpoints to handle authentication stuffs. Once you install WRAT, these endpoints will be registered automatically.

• Access token
• Verify
• Authentication
• Refresh token

Access token

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

Verify

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.

---

Authentication

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.

Refresh token

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
}

List of Error Codes

• 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.

---

Customization

• Action hooks
• Filter hooks
• Functions

Action hooks

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);

Filter hooks

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');

Functions

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

Contribution

Publisher Jafran Hasan

Contributors

• You should be here

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.