OAuth Authentication

OAuth (Open Authorization) is an open standard for token-based authentication and authorization which is used to provide single sign-on (SSO). OAuth allows an end user's account information to be used by third-party services, such as Facebook, without exposing the user's password. It acts as an intermediary on behalf of the end user, providing the service with an access token that authorizes specific account information to be shared.

Token Request

First of all you have to get the access/JWT token to make a resource request, once you get the Token then you can use that token to make a resource request. You can get the access token from the following methods:

  • Password Grant
  • Client Credentials Grant
  • Refresh Token Grant

Password Grant

The Password grant is one of the simplest OAuth grants and involves only one step: the application presents a traditional username and password login form to collect the user’s credentials and makes a POST request to the server to exchange the password for an access token. The POST request that the application makes looks like the example below.

Sample Request
    Request: POST /wp-json/api/v1/token
    Body:
    grant_type = password
    username = < wordpress_username >
    password = < wordpress_password >
    client_id = < client_id >
  • cURL
  • Postman
curl -d "grant_type=password&username=<wordpress_username>&password=<wordpress_password>&client_id=<client_id>" -X POST http://<wp_base_url>/wp-json/api/v1/token

Click here to download POSTMAN collection export

Success Response
Code Status Description
200 SUCCESS You will get the Access Token or ID Token in the response.

Example model:
{
  "token_type":"Bearer",
  "iat":1572861717,
  "expires_in":1572865317,
  "access_token":"XR4vdoz61CLNQIR3",
  "id_token":"HEADER.PAYLOAD.SIGNATURE",
  "refresh_token":"pf7T4CtomfRez4JI4GcqdfNrA"
}
Error Response
Code Error Description
400 INVALID_CREDENTIALS You will get this error when either username or password is incorrect.

Example Model:
{
  "status":"error",
  "error":"INVALID_CREDENTIALS",
  "code":"400" ,
  "error_description":"Invalid username or password."
}
401 INVALID_GRANT_TYPE You will get this error whenever you send incorrect grant type.

Example Model:
{
  "status":"error",
  "error":"INVALID_GRANT_TYPE",
  "code":"401",
  "error_description":"Invalid grant Type."
}
400 INVALID_CLIENT_ID You will get this error whenever you have send incorrect client ID.

Example Model:
{
  "status":"error",
  "error":"INVALID_CLIENT_ID",
  "code":"400",
  "error_description":"Invalid Client ID."
}
400 BAD_REQUEST You will get this error whenever you have missed any parameter to send in the request.

Example Model:
{
  "status":"error",
  "error":"BAD_REQUEST",
  "code":"400",
  "error_description":"Invalid request."
}

Client Credentials Grant

To receive an access token, the client POSTs an API call with the values for client ID and client secret obtained from a registered developer app as follow.

Sample Request
    Request: POST /wp-json/api/v1/token
    Body:
    grant_type = client_credentials
    client_id = < client_id >
    client_secret = < client_secret >
  • cURL
  • Postman
curl -d "grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>" -X POST http://<wp_base_url>/wp-json/api/v1/token

Click here to download POSTMAN collection export

Success Response
Code Status Description
200 SUCCESS You will get the Access Token or ID Token in the response.

Example model:
{
  "token_type":"Bearer",
  "iat":1572861717,
  "expires_in":1572865317,
  "access_token":"XR4vdoz61CLNQIR3",
  "id_token":"HEADER.PAYLOAD.SIGNATURE",
  "refresh_token":"pf7T4CtomfRez4JI4GcqdfNrA"
}
Error Response
Code Error Description
400 INVALID_CLIENT_CREDENTIALS You will get this error when either Client ID or Client Secret is incorrect.

Example Model:
{
  "status":"error",
  "error":"INVALID_CLIENT_CREDENTIALS",
  "code":"400",
  "error_description":"Invalid Client credentials."
}
400 BAD_REQUEST You will get this error whenever you have missed any parameter to send in the request.

Example Model:
{
  "status":"error",
  "error":"BAD_REQUEST",
  "code":"400",
  "error_description":"Invalid request."
}

Refresh Token

To exchange the Refresh Token you received for a new Access Token, make a POST request to the token endpoint, using grant_type=refresh_token as follows.

Sample Request
    Request: POST /wp-json/api/v1/token
    Body:
    grant_type = refresh_token
    refresh_token = < Refresh_Token >
    client_id = < client_id >
    client_secret = < client_secret >
  • cURL
  • Postman
curl -d "grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>&client_secret=<client_secret>" -X POST http://<wp_base_url>/wp-json/api/v1/token

Click here to download POSTMAN collection export

Success Response
Code Status Description
200 SUCCESS You will get the Access Token or ID Token in the response.

Example model:
{
  "token_type":"Bearer",
  "iat":1572861717,
  "expires_in":1572865317,
  "access_token":"XR4vdoz61CLNQIR3",
  "id_token":"HEADER.PAYLOAD.SIGNATURE",
  "refresh_token":"pf7T4CtomfRez4JI4GcqdfNrA"
}
Error Response
Code Error Description
400 INVALID_CLIENT_CREDENTIALS You will get this error when either Client ID or Client Secret is incorrect.

Example Model:
{
  "status":"error",
  "error":"INVALID_CLIENT_CREDENTIALS",
  "code":"400",
  "error_description":"Invalid Client credentials."
}
400 INVALID_REFRESH_TOKEN You will get this error whenever you send incorrect refresh token.

Example Model:
{
  "status":"error",
  "error":"INVALID_REFRESH_TOKEN",
  "code":"400",
  "error_description":"Invalid Refresh Token."
}

Resource Request

Once you get the access_token / id_token, you can use it to request the access to the WordPress site as shown below.

Sample Request
    Request: GET /wp-json/wp/v2/posts
    Header: Authorization : Bearer < access_token / id_token >

The Header is explained below.

  • Authorization : The HTTP Authorization request header contains the credentials or token type and token value to authenticate a user agent with a server, usually after unsuccessful authentication the server has responded with a 401 Unauthorized status.

  • Bearer < access_token / id_token > : The Bearer < access_token / id_token > is created by the Authentication server. When a client application request the authentication server then server authenticate that token and give response to client application accordingly.

  • cURL
  • Postman
curl -H "Authorization:Bearer < access_token / id_token >" -X GET http://<wp_base_url>/wp-json/wp/v2/posts

Click here to download POSTMAN collection export

The server replies with the requested data as the members of a JSON object.

Success Response
Code Status Description
200 SUCCESS Example model:
[{
  "id":1,
  "guid":{
  "rendered":"http://<wp_base_url>/?p=1"
  },
  "slug":"hello-world",
  "status":"publish",
  "type":"post",
  "link":"http://<wp_base_url>/hello-world/",
  "title":{
  "rendered":"Hello World"
  },
  "content":{
  "rendered":"<p>Welcome to WordPress. This is your first post. Edit or delete it, then start writing!<\/p>",
  "protected":false
  },...
}]
Error Response
Code Error Description
400 INVALID_ACCESS_TOKEN You will get this error when you have put an invalid Access Token or expired Access Token.

Example Model:
{
  "status":"error",
  "error":"INVALID_ACCESS_TOKEN",
  "code":"400",
  "error_description":"Invalid Access Token."
}
401 MISSING_AUTHORIZATION_HEADER You will get this error whenever you don't send Header in the API request or It was removed by your server due to some reasons.

Example Model:
{
  "status":"error",
  "error":"MISSING_AUTHORIZATION_HEADER",
  "code":"401",
  "error_description":"Authorization header not received. Either authorization header was not sent or it was removed by your server due to security reasons."
}

NOTE - This error may occur because of server environment, your server may removed your Authorization header due to security reasons.

- If you are using Apache server then put the below line in your htaccess file after the RewriteBase.
  RewriteEngine On
  RewriteCond %{HTTP:Authorization} ^(.*)
  RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]

- If you are using NGINX server then put the below line in your conf file.
  add_header Access-Control-Allow-Headers "Authorization";
400 INVALID_AUTHORIZATION_HEADER_TOKEN_TYPE You will get this error whenever you send the Authorization header but in header you are sending the wrong token type.

Example Model:
{
  "status":"error",
  "error":"INVALID_AUTHORIZATION_HEADER_TOKEN_TYPE",
  "code":"400",
  "error_description":"Authorization header must be type of Bearer Token."
}