Launching and Authenticating the Gateway

Study Notes:

Hello, and welcome to this lesson on the Interactive Brokers Client Portal API. In this tutorial, we will be covering how to configure the Client Portal Gateway, how to authenticate on the Gateway and how to confirm your authentication status. To begin, lets go to the Client Portal API documentation at interactivebrokers.github.io/cpwebapi. The documentation provides all the information you’ll need for utilizing the Client Portal API.

Please note that you will need to have an opened and funded Interactive Brokers account to be able to connect through the Client Portal API.

Setting up and running the Client Portal API Gateway

To begin, let’s first navigate to the Client Portal documentation site, and click on the Quickstart tab on the left. Then, on top right of the Quickstart page you should see the API Gateway and Java download panel for downloading the gateway software and Java installer. The gateway is a Java based program that requires a Java Runtime Environment (JRE) running on your machine. To check if you already have a JRE running, please open the command prompt and type the command ‘java –version’. If you received “’java’ is not recognized as an internal or external command” message, please download and install the Java on your machine following the Java download link. Otherwise, it should return the details of the Java & JRE version, and you are ready to download, extract, and run the gateway. By default, the Client Portal Gateway’s ZIP file will download to your user’s Downloads folder.

Once you have everything downloaded and installed, it is time to run the Gateway and get authenticated. Firstly, open a command prompt terminal and navigate to the directory that you extracted the clientportal.gw folder from step 2.  To do this, use the command ‘cd {Your Directory}\clientportal.gw’. Once you are inside the directory, run the command ‘bin\run.bat root\conf.yaml’ for Windows or ‘bin/run.sh root/conf.yaml’ for Unix. Keep in mind to leave this window open while using the Client Portal gateway.

After the new window has been opened, the gateway should be up and running, and it’s ready to authenticate the user’s session. Let’s open a browser and navigate to https://localhost:5000 on your local network then login with your Live or Paper Account credentials.

Please note that you cannot be logged into the account you are authenticating with anywhere else before you authenticate. You should make sure to log out of the account before attempting to authenticate by using the “Log Out” option on our other platforms. Just closing the window or application may cause a stale login session that could prevent the authentication from working properly so using the log out option is important. If the authentication is successful, a new page will load with the message ‘Client login succeeds’. If the page reloads back to this page again, simply log in again.

For any questions you may have regarding authentication, please visit our Authentication page in our documentation, as your question may already be answered here. A few important questions to highlight are: “How long does a session remain authenticated?”, and “How can I prevent the session from timing out?”

Update gateway certificate

The gateway comes with a default certificate. This will likely present an insecure server message when navigating to the page and making requests to your localhost. It is important to note that the insecure connection is between you and your localhost, or the connection on the same machine. The connection between the localhost and Interactive Brokers will remain secure. However, you may replace it with your own self-signed certificate or public certificate. To update the gateway certificate, replace the default certificate with your own certificate under the gateway directory \root and modify the sslCert and sslPwd fields in the conf.yaml file. And if your gateway was already running, be sure to restart the program.

Using /auth/status

Now, let’s start writing a simple program to confirm our authentication status. This can be called at any point to confirm authentication status on your machine. I will start by creating a new Python program and importing a few modules. We can do this by writing “import requests”.

I will also import a library called “urllib3”. This library gives us access to a method to disable SSL errors when using the default certificate. This is not a required module and is used purely for aesthetics. With this, I will write a quick call for “urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)”

I will also create a confirmStatus() method that contains no arguments. For the moment, I will only put “pass” in this method. Afterwards, I will create the Python Name-Main idiom to automatically run our method if this is the primary file, and reference our confirmStatus() method.

With our framework complete, we can return to our confirmStatus() method to call the endpoint. I will begin with a variable, base_url, and set it equal to “https://localhost:5000/v1/api/”. This is the standard base URL for all requests in the Client Portal API. Now, I will create a variable called ‘endpoint’ which I’ll set to “iserver/auth/status”.

Next, we can build the request. To do this, I will call my variable, auth_req, and set it equal to “requests.get(url=base_url+endpoint, verify=False)”. This will create an http GET request, with a targeted URL of our combined base url and endpoint, or “https://localhost:5000/v1/api/iserver/auth/status”. I had also set the ‘verify’ parameter to False, so that we do not require SSL verification on our request. Finally, I will print the “auth_req” variable, as well as “auth_req.text” this will print both the response as well as the response body. Now we can run the code.

If we take a look at our response in the terminal, I can see we received a “<Response [200]>” indicating an “OK” response. This indicates a successful request. Below that, we can see our body, indicating our authentication and connected status’. While there are more values returned, most of these are inconsequential. If we see “connected” equal to false, there may be an issue with the gateway, and you may wish to relaunch your application. If we see “authenticated” to false, your brokerage session is not authenticated. This can mean that either a stale session prevented your login, or you have recently logged in elsewhere, such as the Trader Workstation. This can end your Client Portal session.

Given our Authenticated and Connected status’ showing ‘true’, that means we are fully authenticated and connected and are now ready to send additional queries for market data or order placement.

Thank you for watching this lesson on Configuring the Client Portal Gateway in the Client Portal API. If you find this lesson helpful, please check out our other lessons in the Client Portal API tutorial series.

Code Snippet – confirmStatus.py

import requests

# Disable SSL Warnings
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

# reauthenticate
def confirmStatus():
    base_url = "https://localhost:5000/v1/api/"
    endpoint = "iserver/auth/status"
    
    auth_req = requests.get(url=base_url+endpoint,verify=False)
    print(auth_req)
    print(auth_req.text)

if __name__ == "__main__":
    confirmStatus()