Phase 1: Authentication Update for the XML based API

kboyapati — Thu, 18 Jul 2019 21:31:58 +0000

Keywords:

This guide will help you get started with the new authentication process into the XML based API. This will not affect clients that are already on the new JSON API through this Developer Portal. The only change for Phase 1 will be the log in request for our existing XML API users. This authentication process must be completed and implemented into your application by January 1, 2020. Any applications on the XML based API not using this system will no longer have access into our API.

Creating a Developer Account

Click the Register link and complete all fields in the new user registration screen. Required fields are indicated with an asterisk.
Click "Create new account"
You will receive an email with a verification link and your new account details. Click the verification link from the email to activate your new account.
After successful login, you can navigate TD Ameritrade for developers with the following menu bar links:
- APIs: Documentation for the APIs provided through TD Ameritrade for developers
- My Apps: Use to create, view, edit, and delete an application and its associated details
- Guides: Contains instructions on how to perform specific tasks with the APIs provided and other useful information to aid in your development

Registering an App

Each user is allowed to create only one app for private, non-commercial use. For more information about commercial usage, please Contact Us after your developer portal account has been created to enable your account for access to registering an application for commercial use.

To create a new app, go to My Apps and select Add a new App
Complete the fields in the Add App screen and select Create App. Field details are:
- App Name: A unique application name.
- Callback URL: The URL to receive the auth code (used to retrieve a token from the Authentication API) after successful authentication. Separate URLs with a comma for multiple URLs. Localhost can be used here, as well. This is also known as a redirect_URI
- What is the purpose of your application?: Use cases of the application, trading strategy, number of orders sent per day, etc.
Your new application will be displayed in My Apps once it is successfully registered. Your Consumer Key is randomly generated and will be available on your Apps page. This application will be associated with the authentication process. Your old source ID (aka API Key) will still be valid until we provide more information in the future. The old source ID is needed for the last section of this guide.

First Authenticated Request

To authenticate a user, we use the OAuth 2.0 Authorization Code flow described in section 1.3.1 of RFC 6749. The best way to see this in action is to follow the steps on the Simple Auth for Local Apps Guide

Invoke the authentication window in the browser with the URL https://auth.tdameritrade.com/auth?response_type=code&redirect_uri={Callback URL}&client_id={Consumer Key}@AMER.OAUTHAP
When the user has authenticated, a GET request will be made to your redirect URI with the authorization code passed as a parameter.
This authorization code, once URL decoded, can then be passed as the code parameter to the Authentication API's Post Access Token method using the ‘authorization_code’ grant type. To receive a refresh token which allows you to receive a new access token after the access token's expiration of 30 minutes, set the access type to ‘offline’. Here is an example of a request to generate your first set of tokens:
1. ```
grant_type: authorization_code
refresh_token: <null>
access_type: offline
code: {URL Decoded Auth Code}
client_id: {Consumer Key}
redirect_uri: {Callback URL}
```

The ‘access_type’ is optional. Set this to ‘offline’ to generate a refresh token along with an access token (preferred). If no refresh token is needed, this field can be left empty.

When you have POSTed details to the token endpoint and received your access token and refresh token, you can pass the access token as a bearer token by setting the Authorization header on all requests to "Bearer Access Token".
To request a new access token, make a Post Access Token request with your refresh token using the following parameter values:
1. ```
grant_type: refresh_token
refresh_token: {REFRESH TOKEN}
client_id: {Consumer Key}
```

Login Request with Old API

This will replace your previous session log in process. All other aspects of the older XML based API will still remain the same for Phase 1. The old authentication process will no longer be available as of January 1, 2020. We will provide more information for Phase 2 in the future, but you can fully migrate now without waiting.

Resource URL: https://apis.tdameritrade.com/apps/100/AuthTokenLogIn

Parameters: The following parameters have to be POSTed:

Header Parameter:

Content-Type: application/x-www-form-urlencoded

Body parameter:

version: 1.0 // version number of client software application.
source: ABC1 // the sourceID previously assigned by TD Ameritrade
authToken: vcOPjPaPlvYHAG915GA... //URL Decoded access token from the previous step.

Response: This will be the same XML response as before. This will establish a session so it can be used in the other XML based API end-points. Everything else will still work the same for Phase1.

More information

If would like to migrate over completely from the old API to the new API now without waiting, here are some useful links:

Our API Endpoints: https://developer.tdameritrade.com/apis

Our Streamer API: https://developer.tdameritrade.com/content/streaming-data

Our Place Order Samples page: https://developer.tdameritrade.com/content/place-order-samples

TD Ameritrade for developer - Phase 1: Authentication Update for the XML based API

Phase 1: Authentication Update for the XML based API

Creating a Developer Account

Registering an App

First Authenticated Request

Login Request with Old API

More information