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.
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/.
The three actors in OAuth are:
|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
- 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.
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:
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.
Here are the credentials:
|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.|
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
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:
|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.
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.
Extensive samples of sandbox requests and responses are included in this documentation for reference purposes.
Accessing the Sandbox
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.
Calls to the sandbox use a slightly different syntax than calls to production. The table below shows both.