Stage 1: Authentication

Authentication is the foundation of all API interactions with the Tradovate API. This stage ensures your integration can properly authenticate and maintain secure access to the platform.

Overview

The authentication stage validates that your application can:

• Request access tokens using valid credentials
• Renew access tokens to maintain active sessions
• Handle authentication errors gracefully

Required Tests

1. Access Token Request

Endpoint: POST /auth/accesstokenrequest

1
{
2
  "errorText": "string",
3
  "accessToken": "string",
4
  "expirationTime": "2024-01-15T09:30:00Z",
5
  "passwordExpirationTime": "2024-01-15T09:30:00Z",
6
  "userStatus": "Active",
7
  "userId": 1,
8
  "name": "string",
9
  "hasLive": true
10
}

Purpose: Obtain an access token for API authentication.

Test Steps:

1. Send a POST request to /auth/accesstokenrequest with valid credentials
2. Verify the response contains a valid access token
3. Verify the response includes an expiration time
4. Test with invalid credentials to ensure proper error handling

Example Request:

1
const response = await fetch('https://demo.tradovateapi.com/v1/auth/accesstokenrequest', {
2
    method: 'POST',
3
    headers: {
4
        'Content-Type': 'application/json',
5
        'Accept': 'application/json'
6
    },
7
    body: JSON.stringify({
8
        name: 'your_username',
9
        password: 'your_password',
10
        appId: 'your_app_id',
11
        appVersion: '1.0.0',
12
        cid: 'your_cid',
13
        sec: 'your_sec'
14
    })
15
});
16
17
const data = await response.json();

Expected Response:

1
{
2
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3
    "expirationTime": "2024-01-01T12:00:00.000Z"
4
}

Validation Criteria:

• ✅ Access token is returned and non-empty
• ✅ Expiration time is included and valid
• ✅ Response time is under 2 seconds
• ✅ Invalid credentials return appropriate error (401 Unauthorized)

2. Access Token Renewal

Endpoint: GET /auth/renewaccesstoken

1
{
2
  "errorText": "string",
3
  "accessToken": "string",
4
  "expirationTime": "2024-01-15T09:30:00Z",
5
  "passwordExpirationTime": "2024-01-15T09:30:00Z",
6
  "userStatus": "Active",
7
  "userId": 1,
8
  "name": "string",
9
  "hasLive": true
10
}

Purpose: Extend an existing access token without creating a new session.

Test Steps:

1. Obtain a valid access token using /auth/accesstokenrequest
2. Use the access token to call /auth/renewaccesstoken before expiration
3. Verify the response contains a new access token
4. Verify the new token has an extended expiration time
5. Test with an expired token to ensure proper error handling

Example Request:

1
const response = await fetch('https://demo.tradovateapi.com/v1/auth/renewaccesstoken', {
2
    method: 'GET',
3
    headers: {
4
        'Authorization': `Bearer ${accessToken}`,
5
        'Accept': 'application/json'
6
    }
7
});
8
9
const data = await response.json();

Expected Response:

1
{
2
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3
    "expirationTime": "2024-01-01T18:00:00.000Z"
4
}

Validation Criteria:

• ✅ New access token is returned and different from original
• ✅ New expiration time is extended beyond original
• ✅ Response time is under 1 second
• ✅ Expired tokens return appropriate error (401 Unauthorized)

Error Handling

Your implementation must handle the following error scenarios:

Common Error Responses

Invalid Credentials (401):

1
{
2
    "error": "Invalid credentials",
3
    "message": "The provided username or password is incorrect"
4
}

Token Expired (401):

1
{
2
    "error": "Token expired",
3
    "message": "The access token has expired and cannot be renewed"
4
}

Rate Limiting (429):

1
{
2
    "error": "Rate limit exceeded",
3
    "message": "Too many requests. Please try again later."
4
}

Best Practices

1. Token Storage: Store access tokens securely and never log them
2. Token Refresh: Implement automatic token renewal before expiration
3. Error Handling: Implement retry logic with exponential backoff
4. Monitoring: Log authentication failures for debugging
5. Session Management
   • Should use a single access token across all API powered services.
   • Should prefer using the /auth/renewaccesstoken endpoint to renew the token instead of requesting a new one.
   • Should request a new token only if the previous one has expired and renewal fails.

Testing Checklist

• Access token request succeeds with valid Credentials
• If implementing retry logic, don’t retry on the case 401: Invalid Credentials
• Access token renewal succeeds with valid token
• Access token renewal fails with expired token
• Response times meet performance requirements
• Error responses are properly handled
• Session management is properly implemented

Next Steps

After completing Stage 1 authentication tests, proceed to Stage 2: Websocket Management.