Skip to main content

Auth Code Flow

Authorization Code Grant Flow#

The authorization code grant type is used to obtain both Access Tokens and Refresh Tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner’s user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

Implementation Guide#

The authorization code grant type allows the end users to authenticate with TradeStation directly and authorize the Client application to make calls on their behalf. Access tokens expire 20 minutes from the time they are issued.

Step-by-Step

1. Redirect user for authentication/authorization#

The client application will route the end-user to our authorization URL:

  • https://signin.tradestation.com/authorize

Query string parameters:

ParameterRequired/OptionalValue
response_typerequiredSet this to code.
client_idrequiredThe client application’s API Key.
audiencerequiredSet this to https://api.tradestation.com.
redirect_urirequiredThe redirect_uri of your application. This must be included in the list of Callback URLs that your API Key is configured with (contact Client Services if you need to add your URL).
scoperequiredA space-separated list of scopes (case sensitive). openid scope is always required. offline_access is required for Refresh Tokens. Example: openid profile offline_access MarketData ReadAccount Trade Crypto. See Scopes for more information.
staterecommendedAn opaque arbitrary alphanumeric string value included in the initial request that we include when redirecting back to your app. This can be used to prevent cross-site request forgery attacks.

Example Authorization URL:

https://signin.tradestation.com/authorize?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=https://exampleclientapp/callback&
audience=https://api.tradestation.com&
state=STATE&
scope=SCOPE

The URL will take you to a TradeStation login page.

2. Client receives Authorization Code#

Upon successful authentication, the user agent (browser) will be redirected to the URL provided, which will include an Authorization Code in the query string.

Example Redirect:

HTTP/1.1 302 Found
Location: https://exampleclientapp/callback?code=AUTHORIZATION_CODE&state=xyzABC123

3. Exchange Authorization Code for Access Token, ID Token and Refresh Token#

The client uses the Authorization Code to request an Access Token, ID Token and Refresh Token via the /oauth/token endpoint using the authorization_code grant type.

This exchange is done via a POST request and the content-type header should be set to application/x-www-form-urlencoded.

Token URL:

  • https://signin.tradestation.com/oauth/token

Parameters:

ParameterRequired/OptionalValue
grant_typerequiredSet this to authorization_code.
client_idrequiredThe client application’s API Key.
client_secretrequiredThe secret for the client application’s API Key.
coderequiredauthorization_code from the previous step.
redirect_urirequiredThe redirect_uri of your app.

Example Request:

curl --request POST \
--url 'https://signin.tradestation.com/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'client_secret=YOUR_CLIENT_SECRET' \
--data 'code=YOUR_AUTHORIZATION_CODE' \
--data 'redirect_uri=https://exampleclientapp/callback'

Example Response:

{
"access_token": "eGlhc2xv...MHJMaA",
"refresh_token": "eGlhc2xv...wGVFPQ",
"id_token": "vozT2Ix...wGVFPQ",
"token_type": "Bearer",
"scope": "openid profile MarketData ReadAccount Trade Crypto offline_access",
"expires_in": 1200
}

ID tokens are used in token-based authentication to cache user profile information and provide it to a client application, thereby providing better performance and experience. The application receives an ID Token after a user successfully authenticates, then consumes the ID token and extracts user information from it, which it can then use to personalize the user's experience. ID Tokens are JSON web tokens (JWT) that will need to be decoded in order to extract the user information for use in your application. Please see the Other Relevant Scopes Table on the Scopes page to learn more about configuring the ID Token.

Access Tokens are set to expire after 20 minutes. Please visit the Refresh Tokens page to learn about using Refresh Tokens to renew your Access Token.