Keywords: 

This guide will help you with questions about Authentication and OAuth. We utilize a standardized OAuth 2.0 token-based authentication flow on our API described in section 1.3.1 of RFC6749. Below are some of the most commonly asked questions related to this authentication flow.

How do I generate my Auth URL?

Your Callback URL (aka redirect_uri) is something that you assign when you first register your application through our Developer Portal.  A Consumer Key (aka client_id) is provided for you once your application is registered.  If you are using the locally hosted callback URL, like https://127.0.0.1:8080 as an example, along with the Consumer Key “ABC1234”, your Auth URL would be the following:

           https://auth.tdameritrade.com/auth?response_type=code&redirect_uri=https%3A%2F%2F127.0.0.1%3A8080&client_id=ABC1234%40AMER.OAUTHAP

What do I use to sign into the Auth URL when creating my token for the first time?

Our Developer Portal and the endpoints listed are available for use with any TD Ameritrade US Broker Dealer clients.  The credentials you use on the initial authentication login process will be the same as you would use to log into www.TDAmeritrade.com .  Note that a Paper Money account on the thinkorswim trading platform is only available through thinkorswim.  Thinkorswim is a separate environment from our API.  There is not a paper money feature available through our API.

This manual login process is only necessary for creating your first set of refresh and access tokens.  This process login process should not be programmatically scripted.

How do tokens work?

Once you have created your first set of tokens, you will have a refresh token and an access token.  A refresh token is valid for 90 days.  They are used to create new refresh and access tokens in the future.  Access tokens are valid for 30 minutes.  These access tokens are used to authenticate into the different APIs.  As long as you have a valid refresh token, use the following parameters with the Post Access Token API (https://developer.tdameritrade.com/authentication/apis/post/token-0) to create only an access token:

  1. grant_type: refresh_token
    refresh_token: <insert valid refresh token>
    client_id: <insert consumer key>

As your refresh token is about to expire, use the following parameters to create a new refresh token:

  1. grant_type: refresh_token
    refresh_token: <insert valid refresh token>
    access_type: offline
    client_id: <insert consumer key>

When I try to create a token, I am getting an invalid_grant error.  What do I do?

This type of an error when using the “grant_type” as “authorization_code” is usually associated with an incorrect “redirect_uri” (aka Callback URL) or incorrect “code” when using the Post Access Token API (https://developer.tdameritrade.com/authentication/apis/post/token-0) as you are creating your first set of tokens.  Ensure your Callback URL is exactly as it appears from your My Apps page (https://developer.tdameritrade.com/user/me/apps) and that your Auth Code is properly URL decoded or encoded based on the framework you are using.

If you are getting this error when using the “grant_type” as “refresh_token”, it means that your refresh token has expired or is no longer valid since it was first created over 90 days ago.  You will need to go through the initial log in process again to recreate a new set of tokens. 

Are there anything else I should know about when interacting with tokens?

Once you have created your first refresh token, the response will provide you with the number of seconds for when a refresh token will expire (translates to 90 days).  The only time you should create another refresh token is around the time when your previous refresh token will expire.   The same will apply for access tokens which is valid for 30 minutes.  Excessive creation of refresh and access tokens is something that we do monitor and is something we will proactively prevent when we notice unusual activity.

Are requests to the Post Access Token API throttled?

Yes. All non-order based requests by personal use non-commercial applications are throttled to 120 per minute. Exceeding this throttle limit will provide a response with a 429 error code to inform you that the throttle limit has been exceeded. There is no need for excessive systematic creation of access and refresh tokens. The above calls to create a token should only be used when your access token is no longer valid or when your refresh token is about to expire.

 

If you see have further questions, please email us directly at API@TDAmeritrade.com for more information.