HFR iRacing API

Introduction

This integration connects the Half Fast Racing League website to the iRacing data API, allowing us to pull member stats, race results, league standings, and more. It uses OAuth 2.0 Authorization Code flow with PKCE (RFC 7636), which is the authentication method mandated by iRacing for third-party integrations.

Key credentials:

• Client ID: half-fast
• Client Type: server-side
• Redirect URIs: https://league.halffast.racing/oauth/callback and https://staging.halffast.racing/oauth/callback
• Audience: data-server
• Test Environment: https://test.halffast.racing

Architecture

The system involves three domains working together:

1. test.halffast.racing — The main test application. Users visit this, initiate login, and see data.
2. league.halffast.racing/oauth/callback — The approved OAuth redirect URI. iRacing sends the user here after they log in. The callback validates state, exchanges the code for tokens, and redirects back to the test app.
3. oauth.iracing.com — iRacing's OAuth server. Handles authentication and issues tokens.

All three subdomains are on the same cPanel account, sharing the same MySQL database (half7175_iracing), which is how the callback can save tokens that the test app then reads.

File Structure

OAuth 2.0 + PKCE Overview

OAuth 2.0 lets our application request permission to access a user's iRacing data without ever knowing their password. The complete flow:

1. User visits login.php and clicks "Login with iRacing"
2. We generate a random code_verifier and derive a code_challenge from it (PKCE)
3. We store the code_verifier in the DB + session for later
4. We redirect the browser to oauth.iracing.com/oauth2/auth with our client_id, redirect_uri, code_challenge, and a random state value
5. The user logs into iRacing and approves access
6. iRacing redirects to league.halffast.racing/oauth/callback with a one-time authorization code and the state value
7. The callback validates the state (CSRF protection), then POSTs the code + code_verifier to oauth.iracing.com/oauth2/token
8. iRacing validates the PKCE pair and returns an access_token (and possibly refresh_token)
9. We store the token in MySQL and redirect back to the dashboard

PKCE Explained

PKCE (Proof Key for Code Exchange, RFC 7636) prevents authorization code interception attacks. Here's how it works:

// Step 1: Generate a random code_verifier (43–128 chars)
$verifier = base64url(random_bytes(64));
// e.g. "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

// Step 2: Hash it to get the code_challenge
$challenge = base64url(sha256($verifier));
// e.g. "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

// Step 3: Send challenge in /authorize (keep verifier secret)
// Step 4: Send verifier in /token — iRacing verifies it matches

This means even if someone intercepts the authorization code, they can't use it because they don't have the code_verifier.

The /authorize Endpoint

URL: https://oauth.iracing.com/oauth2/auth (GET — browser redirect)

On success, iRacing returns HTTP 302 to your redirect_uri with ?code=AUTH_CODE&state=YOUR_STATE. The code is single-use and expires quickly (typically 60 seconds).

The /token Endpoint

URL: https://oauth.iracing.com/oauth2/token (POST — server-to-server, application/x-www-form-urlencoded)

Authorization Code Grant

Trade the authorization code received at your redirect URI for an access token. This is the final step of the OAuth flow.

Refresh Token Grant

If a refresh_token was issued with the initial token response, it can be traded for a new access token without requiring user interaction. Each refresh token is single-use — the response will include a new refresh token.

POST https://oauth.iracing.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=half-fast
&client_secret=MASKED_SECRET
&refresh_token=STORED_REFRESH_TOKEN

Password Limited Grant

For server-side headless clients that run unattended. Only the registered user (the developer) can use this grant — it is not available to the general public. Both the client_secret and password must be masked before sending.

POST https://oauth.iracing.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=password_limited
&client_id=half-fast
&client_secret=MASKED_SECRET             // masked with client_id
&username=your%40email.com
&password=MASKED_PASSWORD             // masked with username
&scope=iracing.auth

Token Response (all grant types)

{
  "access_token":             "eyJhbGciOi...",  // use as Bearer token
  "token_type":               "Bearer",
  "expires_in":               600,               // seconds (10 minutes)
  "refresh_token":            "...",             // may be omitted
  "refresh_token_expires_in": 3600,              // may be omitted
  "scope":                    "iracing.auth"    // may be omitted
            

                
Note on expires_in: The docs show 600 seconds (10 minutes), not 3600 as commonly assumed. Our saveTokens() function uses the actual expires_in value from the response, so this is handled correctly. The refresh_token and refresh_token_expires_in fields may be omitted at iRacing's discretion.