Automating Token Retrieval

Applies to ReadyAPI 3.7, last modified on April 08, 2021

After some period of time, an access token expires. This section describes how to update it automatically.

Automatic retrieval

By default, ReadyAPI updates an access token automatically.

You configure the Refresh Token Access option in the OAuth 2.0 Advanced options dialog. To open it, click Advanced when selecting the OAuth 2.0 profile in the Auth manager or in the Auth panel:

OAuth 2.0 Advanced options: Automatic token update

Click the image to enlarge it.

Retrieve a new access token

The easiest way to update an access token is to use a refresh token that an authorization server issues along with the access token. ReadyAPI stores the refresh token in the project file, so when the access token expires, ReadyAPI requests a new access token by sending a refresh token to the authorization server.

In case a refresh token was not issued or it expires as well, you need to repeat the process of getting an access token. Automation allows you to simulate the needed actions, so ReadyAPI will be able to get a new access token in unattended mode.

Tip: Once it is configured, automation runs even when you get an access token manually in the Get Access Token dialog.
Currently, you cannot get a refresh token from Google, as ReadyAPI does not support sending the access_type and prompt parameters required for that.

Automation editor

You can open the automation editor either in the Auth Manager or in the Auth panel:

In the Auth Manager

In the Auth panel

How automation works

In automation, you create scripts that interact with login, consent, and other screens to grant the permission on behalf of the resource owner:

OAuth 2.0 Automation editor

Click the image to enlarge it.

By using a developer mode in any external browser, you need to inspect web pages involved in the authorization process and find objects to interact with:

OAuth 2.0 Automation: Inspecting a web page

Click the image to enlarge it.

Then, in the Automation editor, you specify JavaScript commands that simulate actions required for granting permission: enters the login and password, clicks the needed buttons, and so on. For example, to simulate getting an access token from the authorization page shown above, you can use the following commands:


document.getElementById("tbUserName").value = "john.smith";
document.getElementById("tbPassword").value = "p@ssw0rd";

During the authorization process, the screens are shown in a particular order. For each screen, you create a separate script in the Automation editor. When you get an access token, ReadyAPI shows the screens in the internal browser and runs scripts one by one. The URL change is a signal for ReadyAPI to run the next script. For example, after entering valid credentials, the authorization server shows the second page, on which it asks you whether you grant permission to the client application. The automation script in this case may look like this:

OAuth 2.0 Automation: Sample automation script

Click the image to enlarge it.

Background redirects may cause the run of the next script, while the page is not in fact changed. Besides that, an authorization server may change the authorization process by adding or skipping pages. For example, when you get an access token for the first time, it asks you to log in, while next time it remembers your account and asks only for a permission. So we recommend that you add the logic to your script that ensures that the script runs on the proper page since ReadyAPI does not detect which page is currently shown.

Follow the links to see examples of how to configure automation with Google OAuth and Azure Active Directory.

Forced token update

By default, ReadyAPI requests a new token only when the old one expires. You can also use scripts to force ReadyAPI to update the token whether it is expired or not.

To do this, you can use the requestAccessCode method of the OltuOAuth2ClientFacade class that assigns a new access token to the specified authorization profile. See the following script as an example:


// Import the required classes

// Get a project
def project = ModelSupport.getModelItemProject(context.getModelItem());

// Get the needed authorization profile
def authProfile = project.getAuthRepository().getEntry("OAuth 2");

//Create a facade object
def tokenType = TokenType.ACCESS;
def oAuthFacade = new OltuOAuth2ClientFacade(tokenType);

// Request an access token in headless mode and assign it to the authorization profile we got earlier
oAuthFacade.requestAccessToken(authProfile, true, true);

// Access token retrieval may take time, so we need to pause the execution for 3 seconds to finish it. You may increase this value if needed.

// Posts a new token to the script log"Set new token: " + authProfile.getAccessToken());

If you are using OAuth 2.0 Azure authorization, replace the OltuOAuth2ClientFacade class in the script with the OltuOAuth2AzureClientFacade class.

On headless machines where the browser window is inaccessible, you can use the same approach as described above. However, there are some things you must do first:

  1. Install and run any X Server.

  2. Specify the display number for your X Server (see the documentation of your X Server).

  3. Open the file in a text editor and add the following line:

    export DISPLAY=<ip>:<index>


    The IP address of the X Server.


    The display number you have specified.

Browser Error

The browser will display all the errors returned by the authorization server.

Sample Browser Error: Google

Click the image to enlarge it.

Validation Error

If some script cannot be validated for some reason, you will get an error message.

Note: The error message is just an assumption. The error may be elsewhere.
Validation Error

Click the image to enlarge it.

See Also

OAuth 2.0 and OAuth 2.0 (Azure)

Highlight search results