Authentication

TD Ameritrade uses OAuth 2.0 to authorize and authenticate requests.

See also

Not familiar with OAuth 2.0? See What is OAuth 2.0? for an overview of OAuth Authentication and Authorization.

Overview

  1. Send Consumer Key and Callback URL from your app’s details to TD Ameritrade
  2. Open web browser to TD Ameritrade, login to TD Ameritrade Brokerage Account
  3. Send authorization code to receive refresh and access tokens
  4. Refresh and access tokens are stored in your api instance’s cache (either DiskCache or MemCache)

Script Application

Script applications are the simplest type of application to work with because they don’t involve any sort of callback process to obtain an access_token.

TD Ameritrade requires that you provide a Callback URL when registering your application – http://localhost:8080 is a simple one to use.

See also

What should my Callback URL be?

pyTD provides a simple web server, written in pure Python, to handle authentication with TD Ameritrade. If used for authentication, this server will run on your localhost (127.0.0.1) and receive your authorization code at your specified Callback URL.

Web Application

If you have a web application and want to be able to access pyTD Enter the appropriate Callback URL and configure that endpoint to complete the code flow.

Installed Application

Token Caching

Warning

To enable persistent access to authentication tokens across sessions, pyTD stores tokens on-disk by default. Storing tokens on-disk may pose a security risk to some users. See Is it safe to save my authentications on-disk? for more information.

By default, tokens are stored on-disk in the Configuration Directory, though they can also be stored in-memory. There are two ways to select a token storage method:

  1. Environment Variable (recommended) - set the TD_STORE_TOKENS variable:
$ export TD_STORE_TOKENS=False
  1. Pass store_tokens keyword argument when creating an api instance to set token storage temporarily:
from pyTD.api import api

oid = "TEST@AMER.OAUTHAP"
uri = "https://localhost:8080"

a = api(consumer_key=oid, callback_url=uri, store_tokens=False)

When store_tokens is set to False, any stored tokens will be freed from memory when the program exits.

Caches

In-Memory - MemCache

The MemCache class provides in-memory caching for authorization tokens.

Important - the stored tokens will be freed from memory when your program exits.

class pyTD.cache.MemCache

In-memory token cache for access and refresh tokens

Attributes:
access_token
refresh_token

Methods

clear  

On-Disk - DiskCache

To store auth tokens on-disk, the DiskCache class is provided. When passed an absolute path, DiskCache creates the necessary directories and instantiates an empty cache file.

class pyTD.cache.DiskCache(config_dir, filename)

On-disk token cache for access and refresh tokens

config_dir

str – Desired directory to store cache

filename

str – Desired cache file name

Usage
-----
>>> c = DiskCache()
>>> c.refresh_token = token
>>> c.access_token = token
Attributes:
access_token
refresh_token

Methods

clear() Empties the cache, though does not delete the cache file