Overview

The E*TRADE Developer Platform uses the OAuth authorization protocol, version 1.0a. OAuth enables an authenticated user to authorize limited access to their account by third-party applications, without exposing user credentials or other sensitive information.

This document provides a brief summary of OAuth and describes how it is used in our developer platform. We recommend that developers be familiar with the detailed OAuth information at: http://oauth.net/core/1.0a/.

OAuth workflow
The three actors in OAuth are:
Role Definition Example
Service provider A service provider that uses OAuth to let a 3rd-party application have limited access to a user's account E*TRADE
User An individual who has an account with the service provider E*TRADE user who uses your application
Consumer A website or application that uses OAuth to access the service provider with the user's permission Your application

A core principle of OAuth is that the service provider can authenticate both the user and the consumer. This provides a secure basis for the user to authorize the consumer for limited access to the user's account on the service provider.

In principle, OAuth authorization requires three steps:

The service provider authenticates the consumer. The service provider authenticates the user. The user authorizes the consumer for limited access to the user's account on the service provider.

E*TRADE OAuth lifecycle

With the E*TRADE Developer Platform, the process works like this:

  • The application uses its own credentials to acquire a temporary request token from E*TRADE by calling the Get Request Token API.
  • Using the Authorize Application API, the application redirects the user, along with the request token, to E*TRADE. There the user logs in to E*TRADE and grants the application limited access to the user's account. E*TRADE generates a verification code, which is passed to the application (manually by the user, or automatically via a callback).
  • The application uses the verification code to acquire an access token that grants temporary access to that user's account. This is done with the Get Access Token API.
  • The access token is included with all requests to the E*TRADE API, identifying the user and authorizing the application.

By default, the token expires at midnight US Eastern time. At that time, the token may be renewed with the Renew Access Token API. When the application terminates or is finished with the token, we recommend that you revoke the token with the Revoke Access Token API.

Callbacks

As mentioned above, when the user authorizes the application, the E*TRADE website generates a verification code that must be passed to the application. One approach is for the user to simply copy the code and paste it into the application. A much better solution is for E*TRADE to automatically redirect the user back to the application, using a callback URL with the verification code added as a query parameter, as shown in these example URLs:

https://myapplicationsite.com/mytradingapp?oauth_verifier=WXYZ89 https://myapplicationsite.com?myapp=trading&oauth_verifier=WXYZ89
Configuring a callback

Using a callback requires that the callback URL be associated with your consumer key in the E*TRADE system. To request this, log in to your E*TRADE account and send a secure message to Customer Service. Select the subject "Technical Issues" and the topic "E*TRADE API". State that you would like to have a callback configured, and specify your consumer key and the desired callback URL. Your callback URL can be just a simple address, or can also include query parameters.

Once the callback is configured, two system behaviors are changed:

The oauth_callback_confirmed property of the request_token API returns TRUE to show that there is a callback URL associated with the consumer key.

Users who approve the authorization request are automatically redirected to the callback URL, with the verification code appended as a query parameter (as shown in the example URLs above).

The User Experience

At runtime, the application redirects the user to the E*TRADE site to authorize the application. There, the user authenticates on a webpage that includes a login form similar to this:

Once logged in, the user is presented with a request to authorize the application to access the account, as shown below.

(Note that an individual consumer key only works with its original user. If any other user attempts to use that key, a non-specific error message is displayed instead of an authorization form, and the process halts.)

The name of the application is displayed (based on the consumer key that was passed to the login page) along with the list of privileges that will be granted - e.g., submit and review orders, retrieve account information, and retrieve market data. If the user agrees to the request, E*TRADE generates a verification code that refers to this agreement.

If a callback URL is associated with the consumer key, the browser is automatically redirected to that URL, with the verification key included as a URL parameter. If not, the user sees a page that displays the verification code, as shown below, and the user has to manually copy the code and paste it into a field in the application.

At that point, the application can send a request to E*TRADE for an access token, attaching the consumer key, the verification code, and an appropriate signature based on the application's consumer secret. The access token grants limited access to the user account for a fixed period of time, and must be attached to all API requests as described below.

Using OAuth Credentials

Once the application has acquired OAuth credentials, as described above, they must be attached to all API requests.

OAuth Credentials
Here are the credentials:
Property Type Required? Description
oauth_consumer_key string Required The value used by the consumer to identify itself to the service provider.
oauth_timestamp integer Required The date and time of the request, in epoch time. Must be accurate within five minutes.
oauth_nonce string Required A nonce, as described in OAuth 1.0a documentation - roughly, an arbitrary or random value that cannot be used again with the same timestamp.
oauth_signature_method string Required The signature method used by the consumer to sign the request. The only supported option is HMAC-SHA1.
oauth_signature string Required Signature generated with the shared secret and token secret using the specified oauth_signature_method, as described in OAuth documentation.
oauth_token string Required The consumer’s access token issued by the service provider.
Timestamp

A timestamp must accompany every REST request, stating the date and time of the request in epoch time (i.e., the number of seconds since 12:00:00 a.m. January 1, 1970 UTC). When the request is received at E*TRADE, the timestamp must be within five minutes of the current UTC time.

Nonce

Every request must include a nonce - an arbitrary or random value, used to ensure that each request is unique. The same nonce can be used for multiple requests, as long as those requests do not have the same timestamp. A typical solution is to generate a random hash for each request.

Signature

The application must include a signature as specified in the OAuth documentation at http://oauth.net/core/1.0a/. The only supported OAuth version is 1.0a, and the only supported hash method is HMAC-SHA1. For compatibility purposes, we recommend using the libraries provided at http://oauth.net.

Note that most of the OAuth examples in this documentation are visually correct but mathematically invalid - i.e., they may not contain values that can be used for testing a signature algorithm. If you wish to test your signature algorithm, use the following table. Given the provided input values, your code should produce the same resulting signature.
Item Value
Key c5bb4dcb7bd6826c7c4340df3f791188
Secret 7d30246211192cda43ede3abd9b393b9
Access Token VbiNYl63EejjlKdQM6FeENzcnrLACrZ2JYD6NQROfVI=
Access Secret XCF9RzyQr4UEPloA+WlC06BnTfYC1P0Fwr3GUw/B0Es=
Timestamp 1344885636
Nonce 0bba225a40d1bbac2430aa0c6163ce44
HTTP Method GET
URL https://etws.etrade.com/accounts/rest/accountlist
Resulting signature %2FXiv96DzZabnUG2bzPZIH2RARHM%3D

Based on this information, your requests should contain the values shown below, although the variables may be in a different sequence.

HTTP header info
Authorization: OAuth oauth_nonce="0bba225a40d1bbac2430aa0c6163ce44",oauth_timestamp="1344885636",oauth_consumer_key="c5bb4dcb7bd6826c7c4340df3f791188",oauth_token="VbiNYl63EejjlKdQM6FeENzcnrLACrZ2JYD6NQROfVI%3D",oauth_signature="%2FXiv96DzZabnUG2bzPZIH2RARHM%3D",oauth_signature_method="HMAC-SHA1"
GET request
https://etws.etrade.com/accounts/rest/accountlist?oauth_consumer_key=c5bb4dcb7bd6826c7c4340df3f791188&oauth_nonce=0bba225a40d1bbac2430aa0c6163ce44&oauth_signature=%2FXiv96DzZabnUG2bzPZIH2RARHM%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1344885636&oauth_token=VbiNYl63EejjlKdQM6FeENzcnrLACrZ2JYD6NQROfVI%3D
Submitting credentials

We recommend that you attach the OAuth information to a request by including it in the HTTP header as XML or JSON, with the header name "Authorization" and the value "OAuth". Here is an example:

Authorization: OAuth oauth_consumer_key="282683cc9e4b8fc81dea6bc687d46758",oauth_timestamp="1273254425", oauth_nonce="LTg2ODUzOTQ5MTEzMTY3MzQwMzE%3D",oauth_signature_method="HMAC-SHA1", oauth_signature="FjoSQaFDKEDK1FJazlY3xArNflk%3D",oauth_token="FiQRgQCRGPo7Xdk6G8QDSEzX0Jsy6sKN14cULcDavAGgU"

As an alternative, the OAuth information can be included as URL parameters. This is usually less desirable, because it creates a long query string and tends to mix API parameters with OAuth parameters. Below is an example of such a query string, for a query that would otherwise have been very eimple.

https://etws.etrade.com/market/rest/quote/IBM?oauth_consumer_key=d85df5b910e3cb47b2a4cf26c20229ae&oauth_nonce=2518627fd47688ae96fec0b2d11b8c24&oauth_signature=FXZWW1N5UkFNcayfpoGXWHsgYNc%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1343164357& oauth_token=eu4zvG1xpZXlA0wGZx4oJDMDPdnna8IsVcVMqNxeKyQ%3D

Note that the E*TRADE API does not recognize OAuth credentials in the body of the HTTP request. The only supported options are the header or the query string.

The OAuth API Module
The OAuth module of the E*TRADE Developer Platform includes the following REST APIs:
API Description
Get Request Token Returns a request token that can be used to initiate authorization.
Authorize Application Using the request token, redirects the user to the E*TRADE authorization page, where the user authorizes the consumer application to access the account. This returns a verification code.
Get Access Token Using the verification code, requests an access token that can be used to access the E*TRADE API on the user's behalf
Renew Access Token Renews the access token when it expires.
Revoke Access Token Revokes the access token at the end of the session.

Each of these APIs is documented separately in detail.

PLEASE READ THE IMPORTANT DISCLOSURES BELOW

By using E*TRADE API ("API") and accepting the terms of the Application Programming Interface License Agreement and the Application Programming Interface User Agreement, you agree that API may employ security policies, procedures and systems of Third Party providers which may or may not be less stringent and secure than the policies, procedures and systems of E*TRADE Securities LLC ("E*TRADE") or its affiliates. Material provided on API may have been produced by independent third parties not affiliated or endorsed by E*TRADE or its affiliates ("Third Party"). To the extent that API or Third Party providers express opinions or make recommendations, you understand that such opinions or recommendations are expressed by the Third Party provider and are not the opinions or recommendations of E*TRADE or its affiliates. E*TRADE is not responsible for the accuracy of market data displayed on API or made available by Third Party providers. There may be latency between the time an order (or other information) is submitted from API and the time the order is received by E*TRADE. The E*TRADE Two Second Execution Guarantee or any similar guarantee does not apply for orders placed through API and Third Party provider web sites. The E*TRADE CompleteTM Protection Guarantee does not apply. Orders created and submitted through API are not vetted until they are received by E*TRADE. It is possible that E*TRADE may reject an order placed through API. Please see the Application Programming Interface License Agreement and the Application Programming Interface User Agreement for more information.


The E*TRADE family of companies provides financial services including trading, investing, and related banking products and services to retail investors.


Securities products and services offered by E*TRADE Securities LLC, Member FINRA/SIPC.


System response and account access times may vary due to a variety of factors, including trading volumes, market conditions, system performance, and other factors.