Basic Authentication

Basic Authentication is a method for an HTTP user agent (e.g. a web browser) to provide a username and password when making a request. In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic <credentials>, where credentials is the base64 encoding of id and password joined by a single colon : .

Basic Auth using Username & Password

In Basic Authentication with username and password when you need to access WordPress REST APIs, you need to send an API request with your respective base64 encoded username:password. You need to use the request format as shown below.

NOTE - In WordPress when you make POST request for the REST APIs, you must need Basic Authentication to make a POST request. Also, the users you are sending in the Header has the capabilities to perform that actions.

Sample Request
    Request: POST /wp-json/wp/v2/posts
    Header: Authorization : Basic base64encoded <username:password>
Sample Request (with HMAC Encryption)
    Request: POST /wp-json/wp/v2/posts
    Header: Authorization : Basic base64encoded <username:password:hmac>

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.

  • Basic base64encoded <username:password> : The Basic base64encoded <username:password> is created by the Authentication server. When a client application request the authentication server then server authenticate that user and give response to client application accordingly.

  • Basic base64encoded <username:password:hmac> : Here, hmac is the SHA-256 hash that is generated by hashing <username:password> with the secret key.

  • cURL
  • Postman
curl -H "Authorization:Basic base64encoded <username:password>" -X POST http://<wp_base_url>/wp-json/wp/v2/posts -d "title=sample post&status=publish" 

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":2,
  "guid":{
  "rendered":"http://<wp_base_url>/?p=2"
  },
  "slug":"sample-post",
  "status":"publish",
  "type":"post",
  "link":"http://<wp_base_url>/sample-post/",
  "title":{
  "rendered":"Sample Post"
  },
  "content":{
  "rendered":"",
  "protected":false
  },...
}]
Error Response
Code Error Description
400 INVALID_USERNAME You will get this error when the username does not exist.

Example Model:
{
  "status":"error",
  "error":"INVALID_USERNAME",
  "code":"400" ,
  "error_description":"Username Does not exist."
}
400 INVALID_PASSWORD You will get this error when the password is incorrect for the username.

Example Model:
{
  "status":"error",
  "error":"INVALID_PASSWORD",
  "code":"400" ,
  "error_description":"Incorrect password."
}
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.
  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";
401 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":"401" ,
  "error_description":"Authorization header must be type of Bearer Token."
}
401 INVALID_TOKEN_FORMAT You will get this error whenever you send the Authorization header but in header you are sending the wrong format to encode token.

Example Model:
{
  "status":"error",
  "error":"INVALID_TOKEN_FORMAT",
  "code":"401" ,
  "error_description":"Sorry, you are not using correct format to encode string."
}

Basic Auth using Client ID & Client Secret

In Basic Authentication with Client ID and Client Secret when you need to access WordPress REST APIs, you need to send an API request with your respective Authorization Key. You need to use the request format as shown below.

Sample Request
    Request: POST /wp-json/wp/v2/users
    Header: Authorization : Basic base64encoded <clientid:clientsecret>
Sample Request (with HMAC Encryption)
    Request: POST /wp-json/wp/v2/posts
    Header: Authorization : Basic base64encoded <clientid:clientsecret:hmac>

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.

  • Basic base64encoded <clientid:clientsecret> : The Basic base64encoded <clientid:clientsecret> is created by the Authentication server. When a client application request the authentication server then server authenticate that client id and client secret and give response to client application accordingly.

  • Basic base64encoded <clientid:clientsecret:hmac> : Here, hmac is the SHA-256 hash that is generated by hashing <clientid:clientsecret> with the secret key.

  • cURL
  • Postman
curl -H "Authorization:Basic base64encoded< clientid:clientsecret > " -X POST  http://<wp_base_url>/wp-json/wp/v2/users -d "username=test&email=test@test.com&password=test&name=test" 

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": 5,
  "username": "test",
  "name": "test",
  "first_name": "",
  "last_name": "",
  "email": "test@test.com",
  "description": "",
  "link": "http://<wp_base_url>/author/test/",...
}
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 ID or client sercret."
}
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.
  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";
401 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":"401",
  "error_description":"Authorization header must be type of Bearer Token."
}
401 INVALID_TOKEN_FORMAT You will get this error whenever you send the Authorization header but in header you are sending the wrong format to encode token.

Example Model:
{
  "status":"error",
  "error":"INVALID_TOKEN_FORMAT",
  "code":"401" ,
  "error_description":"Sorry, you are not using correct format to encode string."
}