Authenticate (with API key)

We utilize JSON Web Tokens to authenticate all requests sent to the API. This process involves obtaining a session token, which is required for future requests.

Logging in with an API key is the only supported way to obtain a token.

Step 1: Gather your credentials

The login request takes two values:

Field	What to send
userName	The username you use to sign in to your firm's trading platform. This is not your email address and not a trading account name or ID. Case does not matter.
apiKey	An API key generated from your firm's trading platform. Keys are long random strings. Copy the whole value exactly as shown when you generate it.

On TopstepX, sign in to the platform and open Settings > API at topstepx.com/settings?tab=api. From there you can create a new key, reveal and copy an existing key, or revoke a key you no longer use.

If you cannot find where to generate a key, contact your firm.

You will also need the connection URLs for your firm, listed here.

Step 2: Request a token

API URL: POST https://api.topstepx.com/api/Auth/loginKey

API Reference: /api/Auth/loginKey

The values below are a template. Replace them with your own username and key.

cURL Request

curl -X 'POST' \
  'https://api.topstepx.com/api/Auth/loginKey' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
    "userName": "jane.trader",
    "apiKey": "k7Qm2vX9pL4nR8sT1wY6zB3cD5fG0hJa"
  }'

Step 3: Store the token

Check that success is true and errorCode is 0, then store the token somewhere safe. Send it as a bearer token on every other request.

Response

{
    "token": "your_session_token_here",
    "success": true,
    "errorCode": 0,
    "errorMessage": null
}

How the token behaves:

• It is valid for 24 hours from the time it is issued. After that, requests fail with HTTP 401 and you must log in again or refresh it with Validate Session before it expires.
• One token works for every REST request and realtime hub connection you open. You do not need to log in per request or per connection.
• Logging in again issues a new token and does not invalidate tokens that are already in use.
• Login requests are rate limited like every other endpoint. See Rate Limits. Log in once and reuse the token rather than logging in before each request.

Error responses

A failed login still returns HTTP 200. Read success and errorCode from the body to find out what went wrong. The one exception is a request body missing userName or apiKey, which is rejected with HTTP 400 before any login check runs.

errorCode	Name	errorMessage	Cause	What to do
3	InvalidCredentials	null	The userName and apiKey pair did not match an active key. The username is wrong (an email address is a common mistake), the key was mistyped, or the key has been revoked.	Confirm you are sending your platform login username. Generate a fresh key in the platform, copy it exactly, and retry.
7	AgreementsNotSigned	Please log into the ProjectX platform and complete the required agreements	Your user has agreements that have not been accepted yet.	Sign in to the trading platform, accept the pending agreements, then retry.
9	ApiSubscriptionNotFound	null	Your user does not have an active subscription, so API tokens cannot be issued.	Confirm your subscription with your firm.
10	ApiKeyAuthenticationDisabled	null	Your firm has turned off API key login.	Contact your firm.

Example of a failed response:

Error

{
    "token": null,
    "success": false,
    "errorCode": 3,
    "errorMessage": null
}