Authenticating with the IBKR Client Portal REST API

Learn about IBKR’s modern REST API to trade, monitor, and manage your IBKR account. Andrew Wise, U.S. API Support Supervisor, gives explanation of Client Portal Gateway and authentication process.

Summary – IBKR Podcasts Ep. 142

The following is a summary of a live audio recording and may contain errors in spelling or grammar. Although IBKR has edited for clarity no material changes have been made.

Mary MacNamara

Hello everybody and welcome to IBKR Podcasts. Today we’re going to be talking to Interactive Broker’s Andrew Wise, who is the U.S. API Support Supervisor, and as you know at Interactive Brokers, we have the TWS API, and we also have something called the REST API. So, we’re going to focus on that a bit today. This will be one of several podcasts devoted to more of a tech-centric focus on the APIs. All right, so to start off, Andrew, what is the REST API?

Andrew Wise

So, a REST API is a more general term for any application programming interface that conforms the constraints of the REST architecture. The REST architecture is a development from the early aughts, which is kind of like the standard web protocol, so that way websites can communicate back and forth to one another, and Interactive Brokers REST Web API specifically allows you to use a lot of the functionality that you might find in the client portal directly in the form of an API.

Mary MacNamara

So, in other words, you’re using the browser, you’re developing within the browser, and you can call the API functions to access data, similar to how client portal displays it, but build your own interface.

Andrew Wise

Exactly. And you can create your own interface, or you could even use the API entirely in an automated sense, so that way you can make all of these calls happening without ever having to physically look at the data yourself. You would be able to program some kind of bot or trading API. Trading AI rather so that way it could handle all of that data coming through and make trades on your behalf.

Mary MacNamara

So, do you use a particular programming language with the REST API? Or is it agnostic. Or how does that go?

Andrew Wise

Yeah. So that’s sort of the beauty of the REST API is that because it does focus on these kinds of standards from the early aughts, most programming languages have some form of integration that allow for RESTful requesting, a popular one we see is the Python Request Library. However, C# implements something very similar. Same thing with JavaScript as well, so it’s really agnostic to any language you like. You can even use direct Curl requests if you’d like to even directly go through your command prompt or terminal.

Mary MacNamara

Do you have to have an active Interactive Brokers account to use the Client Portal REST API?

Andrew Wise

Yes, just like anywhere else in Interactive Brokers, to use the Trader Workstation, Client Portal or any of our APIs, you do need to have a fully funded account with Interactive Brokers. We also do require that Pro accounts are in use. We do not support the Lite accounts or those US Commission free trading accounts at Interactive Brokers. So IBKR Pro and a funded account are required to begin trading with the REST API.

Mary MacNamara

OK, good. Here’s another question. Should you use the gateway or what is a gateway anyway?

Andrew Wise

For most of our customers that use the Client Portal API, you’re going to be using something called the Client Portal Gateway and this is just a means of authentication. It’s a Java client that runs locally that’s typically run in the background, and what that it does, it just makes sure it verifies that all requests going out are going to be sent from you as the user, without having to worry about any potential alternative authentication like no API keys or anything like that are in use. However, some clients might find that they might need a more autonomous solution and for our institutional clients, we support something called Oauth, which they can use to obtain access token, token secret and they can do all of the web requests through an Oauth 1.Oa authentication method.

Mary MacNamara

So, if I have that gateway up and running, do I still need to have Client Portal or TWS up and running? Or is that suitable?

Andrew Wise

Oh, no, no, no. Once you have the client portal Gate, Gateway running, you don’t need to have anything else open, and in fact, we actually encourage you not to just because of the competing market data sessions. So, in the Client Portal Web API we actually have a two-tiered authentication structure and what that means is if you log in with Client Portal initially, you’re going to be able to query things like portfolio endpoints. So that way you can look at your balance and everything, but you won’t actually be able to see market data or trade, but that also allows you to continue trading in other platforms. However, if at any point you would like to trade and you know review market data in the API, you would go through the second brokerage session level authentication to allow you to trade there.

Mary MacNamara

And that is the Oauth or not?

Andrew Wise

Not quite. We have something called the /iserver endpoints and users might be familiar with the iserver/auth/ssodh/init endpoint and what that endpoint allows you to do is and initializes the brokerage session which is separate from the standard login procedure you would use for the gateway.

Mary MacNamara

Ah, OK. And that’s because you’re going to be trading and using market data and so forth. Exactly. OK, good. Glad we got that straightened out. All right, so does my program have to authenticate every single time? How does that work?

Andrew Wise

Yeah. So with the Client Portal Gateway, every time you log in or let’s say every single day, you would want to run the Client Portal Gateway and then go ahead and log in. Just for reference, the way to log in with the Client Portal Gateway is you do bring up a browser screen and it looks like it the same login structure as when you would log into Client Portal. Naturally, however, you’ll get a message for confirmed is true. Just to let you know that you have signed in and then that would enable the web session. From there you can call that /ssodh/init endpoint I mentioned before and then you can authenticate with the brokerage session to begin trading. Just like logging into Client Portal, this will look identical to the way you’re used to. So if you have two-factor authentication on your account, this would be prompted for you each time you logged in on the given day.

Mary MacNamara

OK, that’s good to know. And as we know, sometimes Client Portal does time out. You go get some coffee and you come back, and you have to log in again. So, would that apply here too?

Andrew Wise          

It went to a point, but luckily we would able be able to automate that process and by that I mean if you ever see a message where you are disconnected, you would be able to call that iserver/ssodh/init endpoint once again and that will reauthenticate your session for you, so you can even automate the way to reauthenticate every day.

Mary MacNamara

So, you just have something in the background saying, “Am I still awake or/and if I’m not awake”. OK, good. So why would someone, obviously there’s going to be somebody who knows Python and they’re familiar with it, but why would you use this REST API as opposed to, say for instance, the TWS API?

Andrew Wise

One of the more common reasons that we see these implementations is it’s simply a lighter weight than what you might work with in Trader Workstation API because you don’t have to operate Trader Workstation or a heavier local API resource downloaded for your system. The system can move a lot faster and require a lot less hardware resources.

Mary MacNamara

Or memory, right?

Andrew Wise

Yeah, not as much memory, storage processing, things like that. It could all move a little bit faster because it’s not dealing with as much other software to handle it. Another advantage is that going back to the whole REST API standard, if we’re all on the same kind of communication patterns, a lot more people might be familiar with it without having to go into the niche of the Trader Workstation API, which is a lot more unique than some other API implementations.

Mary MacNamara

So, let’s say here’s a question not on our list, but I’m going to throw this out anyway. I’m just thinking about it. So, let’s say for instance that I know JavaScript and I want to work with the REST API but I want to write an app for my phone. So, can I use it that way? Can I do that with my smartphone?

Andrew Wise

Yeah, absolutely. So that would require that you have the Oauth implementation, so that wouldn’t require an institutional client to some degree. However, you would be able to absolutely make an app for your phone, you would be able to make a local personal website or web page even and you would be able to operate the Client Portal API however you’re like using that kind of interface.

Mary MacNamara

Alright, so that’s good to note. Browser still on your phone. OK, so who obviously you deal with a lot of people in the United States who are using the APIs and who really are the primary users for the REST API.

Andrew Wise

Yeah. So, it’s actually quite a bit of variety. In the long term, I’ve been here about two years in Interactive Brokers. Now and in those two years, it’s typically been more of the kind of individual traders, those independent users, however, in recent years, as things began to develop more and we added more and more feature sets, we’ve seen a lot more in the institutional crowd come along. So, we have a lot of third-party developers, you know, building out larger platforms. I think a lot of customers are familiar with services like Trading View. And then we also have a lot of independent traders like financial advisors that are building websites for themselves to trade or accessible platforms for their clients to log in from their smartphones to kind of work with the API that way.

Mary MacNamara

So, in other words, if I am an advisor and I have some programmers who I’m working with and we have a separate little login for our clients, we can basically authenticate with the Client Portal REST API and then get our reports or kind of white brand the portfolio analyst or something like that?

Andrew Wise

Absolutely, and I’m sure we’ll have an episode on this in the future, but we are going to be introducing a topic called the DAM or digital account management. And that is a platform that a lot of advisors will be using to onboard new client’s, kind of help with funds and banking for their clients and give a better experience to those white branded interfaces that somebody might use for, you know monitoring portfolio data as an end user.

Mary MacNamara

And that’s in development? Or is it already available?

Andrew Wise

That’s already available. And Interactive Brokers right now is actually working to make that more and more popular. We’re trying to get the word out there for more and more advisors and third parties to kind of implement that structure.

Mary MacNamara

OK, that sounds pretty exciting. Alright. So last and final question is let’s say I’m a developer and I want to start working with this and I have an account that’s funded, and it is a Pro account, can I use my paper trading account to set up some sort of sandbox for myself?

Andrew Wise

Oh, absolutely. All of our APIs are fully integrated with both live and paper trading accounts. So, if you do have a paper trading account that you would like to test with, you are more than welcome to do so. The only limitation, once again, would be that your live account is created, funded, all of the same limitations you might see otherwise.

Mary MacNamara

And tell us about this new API education site on the IBKR campus.

Andrew Wise

Certainly. So here at Interactive Brokers, we have been doing our best to build out the IBKR Campus site for all of the API documentation. This currently houses all of the documentation for TWS API, Client Portal API, we’re also building out other APIs such as our Flex Web service and hopefully we’ll be porting our DAM services over there soon. We also host an array of videos and articles on the IBKR Campus that allow people to look up how to integrate Python with Excel, for example. We also have videos start to finish with the Client Portal API using Python and a lot of other beginner friendly videos as well as some more intermediate learning materials there.

Mary MacNamara

Oh, that’s really great!  So, Andrew Wise, thank you so much for educating us on the REST API. The beginning little breadcrumbs of it and we’ll be doing more of these. So, if you do have any comments please let us know and also topics.  So, everybody thank you so much for attending and please leave us a review if you can, wherever you watch your podcast.

Thank you so much.

Client Portal API User Guide