Guides to get you going

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:

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.

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

HTTP header info

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:

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.