Guides to get you going

Refer to these helpful guides to get you up and running. Here you’ll find information on OAuth authorization protocol and workflow, the E*TRADE OAuth lifecycle, the E*TRADE account login user experience, how to use OAuth Credentials, and a short guide to the OAuth API module.

• Authorization
• The Sandbox Environment

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:

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

• 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.
• You will need to use the access token obtained from Get Access Token API but NOT request token for calling E*TRADE API. The access token should be included with all requests to the E*TRADE API, for identifying the user and authorizing the application.

If your application does not make any API requests for two hours, the access token becomes inactive and can be activated again using Renew Access Token API. This API doesn't return new token, but just an indication the token has renewed. By default, the token expires at midnight US Eastern time after which one must login again to secure a new access token. 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:

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:

(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:

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.

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.

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.

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="UOnPVdzExTAgHkcGWLLfeTaaMSM%3D",oauth_signature_method="HMAC-SHA1"

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 simple.

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:

Each of these APIs is documented separately in detail.

Overview

The E*TRADE Developer Platform provides a sandbox environment where developers can safely experiment with the REST API and perform limited testing of applications, without executing any actual transactions in real markets involving real securities or money.

Here's how it works:

• No actual transactions are executed.
• If you submit a request that contains a syntax error, you receive an appropriate error message in response.
• If you submit a valid request, you receive a sample response from stored data.

Sandbox responses use stored data that's intended to provide typical responses for basic use cases. So the responses you receive will not contain current data, and may not exactly match your requests in other ways. For instance, you might request quotes on GOOG and MSFT, and receive AAPL, ORCL, and CSCO instead.

The sandbox provides a simple way for you to check your syntax, test your deserialization code, see how data appears on your UI, and so on.

Sandbox Samples

Extensive samples of sandbox requests and responses are included in this documentation for reference purposes.

Accessing the Sandbox

Sandbox login

To access the sandbox, you need an OAuth consumer key and secret for the sandbox. OAuth is explained separately under Authorization, and the process of requesting a consumer key is explained in the Getting Started guide.

To "log in" to the sandbox (i.e., to acquire an OAuth access token and secret for the session), use your sandbox consumer key and secret, but otherwise use the same OAuth procedure that you would normally use for actual production data, and the same authorization server.

The access token and secret that you receive in response to this request will only work on the sandbox environment, not in the production environment. So as long as you are using your sandbox credentials, there is no chance of accidentally triggering an actual market transaction, even if you accidentally send your request to a production URL.

Sandbox URLs

Calls to the sandbox use a slightly different syntax than calls to production. The table below shows both.

Sample URLs

Generate Sandbox Key

To generate your Sandbox environment access key, please follow this link to our automated Sandbox Key generator. Your key and secret will be shown to you immediately within the web page.

ETRADE Footer

By using E*TRADE API ("API") and accepting the terms of the API Developer License 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 Morgan Stanley Smith Barney LLC ("Morgan Stanley") or its affiliates. Material provided on API may have been produced by independent third parties not affiliated or endorsed by Morgan Stanley 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 Morgan Stanley or its affiliates. Morgan Stanley 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 Morgan Stanley. The E*TRADE Complete TM Protection Guarantee does not apply. Orders created and submitted through API are not vetted until they are received by Morgan Stanley. It is possible that Morgan Stanley may reject an order placed through API. Please see the API Developer License Agreement for more information.

Banking products and services are provided by Morgan Stanley Private Bank, National Association, Member FDIC.

Securities products and investment advisory services offered by Morgan Stanley Smith Barney LLC, Member SIPC and a Registered Investment Adviser. Commodity futures and options on futures products and services offered by E*TRADE Futures LLC, Member NFA. Stock plan administration solutions and services offered by E*TRADE Financial Corporate Services, Inc., and are a part of Morgan Stanley at Work. All entities are separate but affiliated subsidiaries of Morgan Stanley. E*TRADE from Morgan Stanley and Morgan Stanley at Work are registered trademarks of Morgan Stanley.

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

Statement of Financial Condition | About Asset Protection | Account Agreements and Disclosures | Quarterly 606 Report | Business Resiliency Plan | Privacy & Cookies | Your Privacy Choices

© currentYear E*TRADE from Morgan Stanley. All rights reserved. E*TRADE Copyright Policy