Skip to main content

Auth Code Flow With PKCE

Auth Code Flow with Proof Key for Code Exchange (PKCE)#

The Auth Code Flow with PKCE is not the default authentication flow. To request this authorization method, please contact Client Services. The Authorization Code with PKCE flow is available for public clients (e.g., native and single-page applications) due to additional security concerns not addressed by the standard Authorization Code Flow. The PKCE-enhanced Authorization Code Flow introduces a secret created by the calling application that can be verified by the authorization server; this secret is called the Code Verifier. Additionally, the calling app creates a transform value of the Code Verifier called the Code Challenge and sends this value over HTTPS to retrieve an Authorization Code. This way, a malicious attacker can only intercept the Authorization Code, and cannot exchange it for a token without the Code Verifier.

Generic Implementation Guide#

Because the PKCE-enhanced Authorization Code Flow builds upon the standard Authorization Code Flow, the steps are very similar.

Step-by-Step

1. Redirect user for authentication/authorization#

The client application will route the end-user to our authorization URL. The only difference in this step versus the standard Authorization Code Flow is the generation and submission of the hashed code_challenge.

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.
code_challengerequiredThe hashed value of the code_verifier. The code_verifier is a random string between 43-128 characters long and should be hashed via the SHA-256 hashing method.
code_challenge_methodrequiredThe hashing method used (S256).

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&
code_challenge=MChCW5vD-3h03HMGFZYskOSTir7II_MMTb8a9rJNhnI&
code_challenge_method=S256

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. The only difference in this step versus the standard Authorization Code Flow is the submission of the original code_verifier string which was used to generate the hashed code_challenge. The authentication server uses this PKCE process instead of a client_secret to secure the requests.

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.
coderequiredauthorization_code from the previous step.
redirect_urirequiredThe redirect_uri of your app.
code_verifierrequiredThe random string between 43-128 characters long that was hashed to create the code_challenge.

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 'code=YOUR_AUTHORIZATION_CODE' \
--data 'redirect_uri=https://exampleclientapp/callback' \
--data 'code_verifier=5d2309e5bb73b864f989753887fe52f79ce5270395e25862da6940d5'

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.

Auth0 Implementation Guide#

For easy implementation, you can follow one of Auth0's Native Application Quickstarts or Single-Page Quickstarts. You can also choose from their list of SDK's below, which all handle the PKCE logic:

Step-by-Step

  1. The user clicks Login within the application.

  2. Auth0's SDK creates a cryptographically-random code_verifier and from this generates a code_challenge.

  3. Auth0's SDK redirects the user to the Auth0 Authorization Server (/authorize endpoint) along with the code_challenge.

  4. Your Auth0 Authorization Server redirects the user to the login and authorization prompt.

  5. The user authenticates using one of the configured login options and may see a consent page listing the permissions Auth0 will give to the application.

  6. Your Auth0 Authorization Server stores the code_challenge and redirects the user back to the application with an authorization code, which is good for one use.

  7. Auth0's SDK sends this code and the code_verifier (created in step 2) to the Auth0 Authorization Server (/oauth/token endpoint).

  8. Your Auth0 Authorization Server verifies the code_challenge and code_verifier.

  9. Your Auth0 Authorization Server responds with an ID Token and Access Token (and optionally, a Refresh Token).

  10. Your application can use the Access Token to call an API to access information about the user.

  11. The API responds with requested data.