OAuth API Documentation

Authorization Code Grant

• Authorization Request

• The application first needs to decide which permissions it is requesting, then send the user to a browser to get their permission. To initiate this authorization flow, form a URL as below and redirect the end user's browser to the URL:

            GET http://<wp_base_url>/wp-json/moserver/authorize
            ?response_type=code
            &client_id= <client_id_goes_here>
            &redirect_uri= <callback_url>
            &scope= <permissions_requesting>
            &state= <security_token>
          

• response_type=code : The type of response you are expecting. To recieve authorization code it must have value code. This tells authorization server that application is initiating authorization flow.
• client_id : The Client ID provided by the OAuth provider.
• redirect_uri : Callback Url to which user will be redirected once they allow or disallow the access to your app.
• scope : One or more space seperated strings which indicates the permission your application requesting.
• state : The application generates a random string and includes it in the request. It should then check that the same value is returned after the user authorizes the app.
• If the user allows access to your app, thier browser will be redirected to the supplied redirect url and request will include code and state parameters in the query string.
• For example, the user can be redirected back to URL such as

              https://example-app.com/redirect
              ?code=<authorization-code>
              &state=<security_token>
          

• The code is Authorization code which can be exchanged for Access token. It is generated by the authorization server and is relatively short lived.
• The state is the same security token that the application initially set in the request.

• Token Request

• If the end user granted your app access and you receive an Authorization Code, you can exchange the Authorization Code for an Access Token by making a POST request to the token endpoint.
• The following is an example for POST request:

              POST http://<wp_base_url>/wp-json/moserver/token
              Content-Type: application/x-www-form-urlencoded
         
              grant_type=authorization_code&
              code=<authorization_code>&
              client_id=<client_id>&
              client_secret=<clientSecret>&
              redirect_uri=<redirect_uri>
              
              

• Here, is the description for each request parameter.
• grant_type=authorization_code : The type of grant you are providing. This tells that the application is using authorization code grant type.
• code : The authorization code recieved in previous step, included here.
• redirect_uri: The same uri that was provided earlier in the authorization request.
• client_id : The client ID provided by the OAuth provider.
• client_secret : The client secret provided by the OAuth provider.
• At the token endpoint all the parameters in the request will be verified ensuring that the code hasn't expired and the client id and secret matches. If the Request is successful, it will generate an access token and return it in the response:

              HTTP/1.1 200 OK
              Content-Type: application/json
              Cache-Control: no-store
              {
                "access_token":"hkjher92u9eu2u3uihi2eh9293",
                "token_type":"bearer",
                "expires_in":3600,
                "scope":"profile",
                "id_token":""
              }
              

• Here, is the description for each parameter received in the response.
• access_token : access token for the Userinfo endpoint.
• token_type : OAuth 2.0 token type value. The value must be Bearer.
• expires_in : The expiry time for the access token.
• scope: One or more space seperated strings which indicates the permission your application requesting.
• id_token: The ID Token is a security token that contains Claims about the authentication of an End-User by an Authorization Server when using a Client, and potentially other requested Claims
• If the request fails the response will have a status of 404 Bad Request and will have the following contents:

              "error" : "invalid_request",
              "error_description" : "A more detailed description of the error intended for the developer of your app."
          

• Resource Request

• If the token request is successful, you will get access_token in the response which can be used to access the protected resources via the API.
• Userinfo Request: The following is a non-formative example of Userinfo Request:

                   GET http://<wp_base_url>/wp-json/moserver/resource
                   Host: server.example.com
                   Authorization: Bearer <access_token>
                

• The resource server validate and verify the access token and checks if it has not expired. If the resource request is valid the resource server returns the claims which are represented by a JSON object that contains a collection of name and value pairs for the Claims.
• Successful Userinfo Response:
• The UserInfo Claims MUST be returned as the members of a JSON object.
  
  Below is the example:

                {
                  "id": "1",
                  "username": "abc",
                  "first_name": "xyz",
                  "last_name": "example",
                  "picture": "https://example.com/-kwtzesU/photo.jpg",
                  "email": "abc@example.com",
                  "locale": "en",...
                }
          

Implicit Code Grant

• Authorization Request

• The application first needs to decide which permissions it is requesting, then send the user to a browser to get their permission. To initiate this implicit flow, form a URL as below and redirect the end user's browser to the URL:

              Get http://<wp_base_url>/wp-json/moserver/authorize 
              ?response_type=token
              &client_id= <client_id_goes_here>
              &redirect_uri= <callback_url>
              &scope= <permissions_requesting>
              &state= <security_token>
          

• response_type=token : The type of response you are expecting. This tells authorization server that application is initiating implicit flow. Note the difference from the Authorization Code flow where this value is set to code.
• client_id : The Client ID provided by the OAuth provider.
• redirect_uri : Callback Url to which user will be redirected once they allow or disallow the access to your app.
• scope : One or more space seperated strings which indicates the permission your application requesting.
• state : The application generates a random string and includes it in the request. It should then check that the same value is returned after the user authorizes the app.
• If the user allows access to your app, thier browser will be redirected to the supplied redirect url and request will include token and state parameters in the query string.
• For example, the user can be redirected back to callback URL such as

        https://callback-url?
        #access_token=<access_token>
        &token_type=Bearer
        &expires_in=3600
        &scope=<permissions_requesting>
        

• Note the two major differences between this and the Authorization Code flow: the access token is returned instead of the authorization code in the response.
• The client can then use the access_token to access protected resources from Resource server.
  Here, is the description for each parameter received in the response.
• access_token : access token for the Userinfo endpoint.
• token_type : OAuth 2.0 token type value. The value must be Bearer.
• expires_in : The expiry time for the access token.
• scope: One or more space seperated strings which indicates the permission your application requesting.

• Resource Request

• The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. The returned Claims are represented by a JSON object that contains a collection of name and value pairs for the Claims.
• Userinfo Request: The following is a non-formative example of Userinfo Request:

             GET http://<wp_base_url>/wp-json/moserver/resource
             Host: server.example.com
             Authorization: Bearer <access_token>
          

• Successful Userinfo Response:
• The UserInfo Claims MUST be returned as the members of a JSON object.
  
  Below is the example:

          {
            "id": "1",
            "username": "abc",
            "first_name": "xyz",
            "last_name": "example",
            "picture": "https://example.com/-kwtzesU/photo.jpg",
            "email": "abc@example.com",
            "locale": "en",...
          }
          

Password Grant

• The resource owner password (or "password") grant type is mostly used in cases where the app is highly trusted. In this configuration, the user provides their resource server credentials (username/password) to the client app, which sends them in an access token request.

• Token Request

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

          POST http://<wp_base_url>/wp-json/moserver/token
          Host: authorization-server.com
          Content-type: application/x-www-form-urlencoded
  
          grant_type=password
          &username=exampleuser
          &password=12345678
          &client_id=xxxxxxxxxx
          &client_secret=xxxxxxxxxx
          

• The POST parameters in this request are explained below.
• grant_type=password : This tells the server we’re using the Password grant type
• username= The user’s username that they entered in the application
• password= The user’s password that they entered in the application
• client_id= The public identifier of the application that the developer obtained during registration
• client_secret= The client secret provided by the OAuth provider.
• At the token endpoint all the parameters in the request will be verified ensuring that the code hasn't expired and the client id and secret matches. If the Request is successful, it will generate an access token and return it in the response:

            HTTP/1.1 200 OK
              Content-Type: application/json
              Cache-Control: no-store
              {
                "access_token":"hkjher92u9eu2u3uihi2eh9293",
                "token_type":"bearer",
                "expires_in":3600,
                "scope":"profile",
                "id_token":""
              }
              

• The client can then use the access_token to access protected resources from Resource server.
  Here, is the description for each parameter received in the response.
• access_token : access token for the Userinfo endpoint.
• token_type : OAuth 2.0 token type value. The value must be Bearer.
• expires_in : The expiry time for the access token.
• scope: One or more space seperated strings which indicates the permission your application requesting.

• Resource Request

• The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. The returned Claims are represented by a JSON object that contains a collection of name and value pairs for the Claims.
• Userinfo Request: The following is a non-formative example of Userinfo Request:

             GET http://<wp_base_url>/wp-json/moserver/resource
             Host: server.example.com
             Authorization: Bearer <access_token>
          

• Successful Userinfo Response:
• The UserInfo Claims MUST be returned as the members of a JSON object.
  
  Below is the example:

          {
            "id": "1",
            "username": "abc",
            "first_name": "xyz",
            "last_name": "example",
            "picture": "https://example.com/-kwtzesU/photo.jpg",
            "email": "abc@example.com",
            "locale": "en",...
          }
          

Client Credentials Grant

• Client Credentials grant can be used for machine to machine authentication. In this grant a specific user is not authorized but rather the credentials are verified and a generic access_token is returned..

• Token Request

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

          POST http://<wp_base_url>/wp-json/moserver/token
              Content-Type: application/x-www-form-urlencoded
         
              grant_type=client_credentials&
              client_id=<client_id>&
              client_secret=<clientSecret>&
              redirect_uri=<redirect_uri>&
              scope=<permisssions_requested>
          



• Request Parameters:
• The POST request parameters are explained below.
• grant_type=client_credentials : This tells the server we’re using the client credentials grant type.
• client_id= The public identifier of the application that the developer obtained during registration.
• client_secret: The client secret provided by the OAuth provider.
• redirect_uri : Callback Url to which user will be redirected once they allow or disallow the access to your app.
• scope : One or more space seperated strings which indicates the permission your application requesting.
• If the credentials are valid, the application will receive back a signed JSON Web Token or access token, the token's type (which is Bearer), and in how much time it expires in Unix time .
• Sample Response

        {
          "access_token": <access_token>,
          "expires_in": 600,
          "token_type": "Bearer"
        }
          

• Response Elements:
• access_token : access token for the Userinfo endpoint.
• expires_in The expiry time for the access token.
• token_type: OAuth 2.0 token type value. The value must be Bearer.

• Resource Request

• The Client Credentials Grant does not support Resource Request.

Refresh Token Grant

• A Refresh Token allows the application to issue a new Access Token or ID Token without having to re-authenticate the user. This will work as long as the Refresh Token has not been revoked.

• Token Request

• The response of token request should contain access token ans refresh token.

            {
              "access_token": "etMv23....429hiU32Hri",
              "refresh_token": "GEbRxBN...edjnXbL",
              "token_type": "Bearer"
            }
            

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

              POST http://<wp_base_url>/wp-json/moserver/token
              Content-Type: application/x-www-form-urlencoded
              grant_type=refresh_token&
              client_id=<client_id>&
              client_secret=<client_secret>&
              refresh_token=<refresh_token>
            

• Here, is the description for each request parameter.
• grant_type=refresh_token : This tells the server we’re using the refresh token grant type.
• client_id= The public identifier of the application that the developer obtained during registration.
• client_secret: The client secret provided by the OAuth provider.
• refresh_token : The refresh token to use.
• The response will include a new Access Token, its type, its lifetime (in seconds), and the granted scopes. If the scope of the initial token included openid, then a new ID Token will be in the response as well.
• Response will contain parameters as follows:

            {
              "access_token": "eyJ...MoQ",
              "expires_in": 86400,
              "scope": <scope>,
              "id_token": "eyJ...0NE",
              "token_type": "Bearer"
            }
            

Revoke a Refresh Token

• Since Refresh Tokens never expire, it is essential to be able to revoke them in case they get compromised.
• To revoke a Refresh Token, you can send a POST request to token endpoint as follows.

            POST http://<wp_base_url>/wp-json/moserver/token
            Content-Type: application/x-www-form-urlencoded
            client_id=<client_id>&
            client_secret=<client_secret>&
            refresh_token=<refresh_token>
          

---

Free Trial

If you don't find what you are looking for, please contact us at info@miniorange.com or call us at +1 978 658 9387 to find an answer to your question about Wordpress OAuth Server.