Authentication

Authentication

The iRacing Data Client uses OAuth2 for authentication. You’ll need OAuth credentials from iRacing — see OAuth Client Credentials to register.

How Authentication Works

The SDK handles the OAuth2 flow automatically:

1. Initial Authentication - Exchanges your credentials for an access token
2. Token Management - Stores and manages access and refresh tokens
3. Automatic Refresh - Refreshes the token automatically before it expires
4. Request Signing - Includes Bearer token authorization in all requests

Note

The SDK manages all authentication complexity internally. You provide credentials, and it handles token lifecycle automatically.

Authentication Methods

Password Limited Flow

The most common flow for server-side applications:

Basic Setup

import { IRacingDataClient } from 'iracing-data-client';

const iracing = new IRacingDataClient({
  auth: {
    type: 'password-limited',
    clientId: process.env.IRACING_CLIENT_ID,
    clientSecret: process.env.IRACING_CLIENT_SECRET,
    username: process.env.IRACING_USERNAME,
    password: process.env.IRACING_PASSWORD,
  },
});

With Token Callback

const iracing = new IRacingDataClient({
  auth: {
    type: 'password-limited',
    clientId: process.env.IRACING_CLIENT_ID,
    clientSecret: process.env.IRACING_CLIENT_SECRET,
    username: process.env.IRACING_USERNAME,
    password: process.env.IRACING_PASSWORD,
    onTokenRefresh: (token) => {
      // Persist token for reuse across restarts
      saveToken(token);
    },
  },
});

Authorization Code Flow

For applications where users authenticate through their browser:

import { buildAuthorizationUrl, exchangeAuthorizationCode, IRacingDataClient } from 'iracing-data-client';

// Step 1: Build the authorization URL
const { url, pkce } = await buildAuthorizationUrl({
  clientId: process.env.IRACING_CLIENT_ID,
  redirectUri: 'http://localhost:3000/callback',
  scope: 'openid',
});

// Step 2: Redirect user to `url`, then handle the callback
const token = await exchangeAuthorizationCode({
  clientId: process.env.IRACING_CLIENT_ID,
  clientSecret: process.env.IRACING_CLIENT_SECRET,
  code: callbackCode,
  redirectUri: 'http://localhost:3000/callback',
  codeVerifier: pkce?.verifier,
});

// Step 3: Create client with the obtained token
const iracing = new IRacingDataClient({
  auth: {
    type: 'authorization-code',
    clientId: process.env.IRACING_CLIENT_ID,
    clientSecret: process.env.IRACING_CLIENT_SECRET,
    tokens: {
      accessToken: token.access_token,
      refreshToken: token.refresh_token,
      expiresAt: Math.floor(Date.now() / 1000) + token.expires_in,
    },
  },
});

Security Best Practices

Never Hardcode Credentials

Always use environment variables or secure vaults for credentials. Never commit credentials to version control.

Use Secrets Management

In production, use proper secrets management like AWS Secrets Manager, HashiCorp Vault, or Azure Key Vault.

Client-Side Security

Never expose your OAuth credentials in client-side code. Always authenticate on the backend.

Rotate Credentials

Regularly rotate your client secret and update your application configuration accordingly.

Environment Variables

Set these environment variables for your application:

IRACING_CLIENT_ID=your-client-id
IRACING_CLIENT_SECRET=your-client-secret
IRACING_USERNAME=your-iracing-email
IRACING_PASSWORD=your-iracing-password

Caution

Always add .env* files to your .gitignore:

.env*
!.env.example

Authentication Errors

The SDK provides specific error types for authentication issues:

import { IRacingDataClient, IRacingError, OAuthError } from 'iracing-data-client';

try {
  const data = await iracing.track.get();
} catch (error) {
  if (error instanceof OAuthError) {
    console.error('OAuth error:', error.message);
    console.error('Error code:', error.code); // e.g. 'invalid_grant', 'invalid_client'
  } else if (error instanceof IRacingError && error.isUnauthorized) {
    console.error('Authentication failed - check your credentials');
  }
}

Next Steps

• Error Handling - Handle auth errors gracefully
• API Reference - Learn about client configuration
• Examples - See authentication in action