Authentication

The TopStep Simulator API uses bearer token authentication. You generate an API key in the TestMax web app, exchange it for a token via the Auth/loginKey endpoint, and then include that token in every subsequent request.

Authentication flow

1. Generate an API key

   Log into testmax.io and navigate to Settings > API Keys. Click Generate New Key. Copy the key immediately — it will not be shown again.

   Caution

   Store your API key securely. Treat it like a password. Do not commit it to source control or share it publicly. Use environment variables to pass it to your scripts.

2. Exchange the API key for a token

   Call POST Auth/loginKey with your email address and API key. The response contains a bearer token.

3. Include the token in all requests

   Pass the token in the Authorization header:

   Authorization: Bearer <your-token>

4. Refresh or validate as needed

   Use POST Auth/validate to check if a token is still valid or to refresh it. Use POST Auth/logout to invalidate a token when done.

---

POST Auth/loginKey

Authenticate with your email address and API key to receive a bearer token.

URL: POST /api/topstep-sim/Auth/loginKey

Request body

{
  "userName": "your@email.com",
  "apiKey": "your-api-key-here"
}

Field	Type	Required	Description
userName	string	Yes	Your TestMax account email address
apiKey	string	Yes	The API key generated in Settings

Response

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

Field	Type	Description
token	string	Bearer token to use in subsequent requests

Example

Python

import urllib.request
import json

API_URL = "https://api.test-max.com/api/topstep-sim"

# Step 1: Authenticate
login_data = json.dumps({
    "userName": "your@email.com",
    "apiKey": "your-api-key-here"
}).encode()

req = urllib.request.Request(
    f"{API_URL}/Auth/loginKey",
    data=login_data,
    headers={"Content-Type": "application/json"}
)
resp = json.loads(urllib.request.urlopen(req).read())

if resp["success"]:
    token = resp["token"]
    print(f"Authenticated. Token: {token[:20]}...")
else:
    print(f"Login failed: {resp['errorMessage']}")

cURL

curl -X POST https://api.test-max.com/api/topstep-sim/Auth/loginKey \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "your@email.com",
    "apiKey": "your-api-key-here"
  }'

JavaScript

const response = await fetch(
  "https://api.test-max.com/api/topstep-sim/Auth/loginKey",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      userName: "your@email.com",
      apiKey: "your-api-key-here",
    }),
  }
);

const data = await response.json();

if (data.success) {
  console.log("Token:", data.token);
} else {
  console.error("Login failed:", data.errorMessage);
}

Error responses

Scenario	errorCode	errorMessage
Invalid API key	1	"Invalid credentials"
Missing fields	1	"userName and apiKey are required"
Account disabled	1	"Account is disabled"

---

POST Auth/validate

Validate an existing token. Returns the same token if valid, or a refreshed token if the original is close to expiration.

URL: POST /api/topstep-sim/Auth/validate

Request headers

Authorization: Bearer <your-token>
Content-Type: application/json

Request body

{}

An empty JSON body is required.

Response

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

Field	Type	Description
token	string	The validated (or refreshed) token

Example

Python

req = urllib.request.Request(
    f"{API_URL}/Auth/validate",
    data=b"{}",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
)
resp = json.loads(urllib.request.urlopen(req).read())

if resp["success"]:
    token = resp["token"]  # Use the refreshed token
    print("Token is valid")
else:
    print("Token expired — re-authenticate")

cURL

curl -X POST https://api.test-max.com/api/topstep-sim/Auth/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{}'

Tip

Call Auth/validate at the start of a script if you have a cached token from a previous session. This avoids an unnecessary loginKey call and gives you a fresh token if the cached one is about to expire.

---

POST Auth/logout

Invalidate a token. After logout, the token can no longer be used for any API calls.

URL: POST /api/topstep-sim/Auth/logout

Request headers

Authorization: Bearer <your-token>
Content-Type: application/json

Request body

{}

Response

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

Example

Python

req = urllib.request.Request(
    f"{API_URL}/Auth/logout",
    data=b"{}",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
)
resp = json.loads(urllib.request.urlopen(req).read())
print("Logged out" if resp["success"] else "Logout failed")

cURL

curl -X POST https://api.test-max.com/api/topstep-sim/Auth/logout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{}'

---

GET Status/ping

Health check endpoint. Returns a simple response indicating the API is operational. No authentication required.

URL: GET /api/topstep-sim/Status/ping

Response

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

Example

curl https://api.test-max.com/api/topstep-sim/Status/ping

---

Using the token in your scripts

Once authenticated, include the token in every request:

import urllib.request
import json

API_URL = "https://api.test-max.com/api/topstep-sim"
TOKEN = "your-token-here"

def api(path, body=None):
    """Call any TopStep Simulator API endpoint."""
    data = json.dumps(body).encode() if body else None
    req = urllib.request.Request(
        f"{API_URL}/{path}",
        data=data,
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Bearer {TOKEN}"
        }
    )
    return json.loads(urllib.request.urlopen(req).read())

# Now use it for any endpoint
accounts = api("Account/search", {"onlyActiveAccounts": True})
contracts = api("Contract/search", {"searchText": "NQ"})

Note

If you are writing strategies in the Algo Playground, authentication is handled automatically. The api() function, TOKEN, and API_URL are all set up for you in the auto-generated script header. You do not need to call Auth/loginKey yourself.

Security best practices

• Never hardcode API keys in your scripts. Use environment variables: os.environ["TESTMAX_API_KEY"]
• Do not commit tokens or keys to version control. Add them to .gitignore or use a .env file
• Rotate keys periodically in Settings > API Keys. Old keys can be revoked at any time
• Log out when done by calling Auth/logout to invalidate tokens after a script completes
• Use one key per integration so you can revoke access to a single script without affecting others