iRacing.com Auth Service

https://oauth.iracing.com/oauth2/book
Admin
iRacing.com provides an OAuth 2.0 compatible service for authentication and authorization, with this...
Tokens:43,885
Snippets:250
Trust Score:9.9
Update:10 months ago
Show doc for...
Tokens:
Raw
### HTTP GET Request Example

Source: https://oauth.iracing.com/oauth2/book/reading_this_book

Demonstrates a typical HTTP GET request to an iRacing.com API endpoint. It shows the request method, URL with parameters, HTTP version, and the Authorization header for token-based authentication. This format is used for invoking endpoints and receiving responses.

```http
GET https://oauth.iracing.com/oauth2/some/endpoint?example=true&another=false HTTP/1.1
Authorization: Bearer ...elided...

```

--------------------------------

### HTTP GET Request Example

Source: https://oauth.iracing.com/oauth2/book/reading_this_book

This section demonstrates the structure of a typical HTTP GET request for the iRacing.com Auth Service API.

```APIDOC
## GET /oauth2/some/endpoint

### Description
This endpoint retrieves data from the iRacing.com Auth Service. It showcases how to structure a GET request with query parameters and an Authorization header.

### Method
GET

### Endpoint
`https://oauth.iracing.com/oauth2/some/endpoint`

### Parameters
#### Query Parameters
- **example** (boolean) - Optional - An example query parameter.
- **another** (boolean) - Optional - Another example query parameter.

#### Request Body
This endpoint does not require a request body.

### Request Example
```http
GET https://oauth.iracing.com/oauth2/some/endpoint?example=true&another=false HTTP/1.1
Host: oauth.iracing.com
Authorization: Bearer ...elided...

```

### Response
#### Success Response (200)
- **message** (string) - A success message.

#### Response Example
```json
{
  "message": "Data retrieved successfully"
}
```
```

--------------------------------

### Main function example for PKCE in Rust

Source: https://oauth.iracing.com/oauth2/book/print

Demonstrates the usage of `code_verifier`, `code_challenge`, and `is_valid` functions in Rust to generate and validate a PKCE pair. It shows how to print the generated verifier and challenge, and then checks their validity.

```rust
use base64::prelude::{Engine, BASE64_URL_SAFE_NO_PAD};
use rand::{thread_rng, Rng};
use regex::Regex;
use sha2::{Digest, Sha256};

// This code is demonstrative, not performant.
// These are the characters that can be accepted as part of
// a code verifier.  They are being stored as a byte array.
const CHARS: &[u8] = b"\ABCDEFGHIJKLMNOPQRSTUVWXYZ\abcdefghijklmnopqrstuvwxyz\1234567890-._~";

/// Generate a code verifier of the given length.
///
/// # Panics
///
/// This code panics if the length is less than
/// 43 or greater than 128.
fn code_verifier(len: usize) -> String {
    assert!(len >= 43);
    assert!(len <= 128);
    // Use a cryptographically strong random number generator.
    let mut rng = thread_rng();
    (0..len) // for each in 0 to len exclusive
        .into_iter() // iterate
        .map(|_| rng.gen_range(0..CHARS.len())) // get an index into CHARS
        .map(|i| CHARS[i]) // get the byte at the index
        .map(char::from) // map it back to a character
        .collect() // collect the characters into a String
}

/// Generate a code challenge for the given verifier.
///
/// # Panics
///
/// This code panics if the given code verifier is less
/// than 43 characters long or greater than 128 characters.
fn code_challenge(code_verifier: String) -> String {
    assert!(code_verifier.len() >= 43);
    assert!(code_verifier.len() <= 128);
    code_verifier
        .chars() // get the characters in the String
        .for_each(|c| { // for each character
            assert!(CHARS.contains(&(c as u8))); // check that it is valid
        });
    // Prepare a SHA256 hash.
    let mut sha256 = Sha256::new();
    // Update the hash with the verifier.
    sha256.update(code_verifier);
    // Compute the final hash.
    let result = sha256.finalize();
    // Encode it as base64.
    let base64 = base64::engine::general_purpose::STANDARD.encode(&result[..]);
    // Make the base64 encoding "URL Safe" and remove the padding.
    base64
        .chars() // get the characters
        .filter_map(|c| match c {
            '=' => None,      // remove padding
            '+' => Some('-'), // make URL Safe
            '/' => Some('_'), // make URL Safe
            x => Some(x),     // return anything else untouched
        })
        .collect() // collect it into a String
}

/// Validate a code verifier and challenge pair.
/// The value `true` is returned when valid.
///
/// This is another way of writing the `code_challenge` function.
fn is_valid(code_verifier: String, code_challenge: String) -> bool {
    let re = Regex::new(r"^[A-Za-z0-9_\.\-\~]{43,128}$").unwrap();
    if !re.is_match(&code_verifier) {
        return false;
    }
    let digest = Sha256::digest(code_verifier.as_bytes());
    let encoded = BASE64_URL_SAFE_NO_PAD.encode(digest);
    // If the given verifier matches the challenge, the server
    // will accept the pair.
    encoded == code_challenge
}

fn main() {
    /// Prefer the maximum.
    let code_verifier = code_verifier(128);
    // Override it with your own by uncommenting the following
    // and replacing the contents of the string:
    // let code_verifier = "5-Giz4oGgbRTt2Q2VmhQMKw_aTp9UJCQuD_~ZAlP-QM".to_string();
    println!("code_verifier: {code_verifier}");
    let code_challenge = code_challenge(code_verifier.clone());
    // Override it with your own by uncommenting the following
    // and replacing the contents of the string:
    //let code_challenge = "-FG7uN-lx34GXN3xvKEPcwqoYnGX2R4ACX59z_X28vE".to_string();
    println!("code_challenge: {code_challenge}");
    if is_valid(code_verifier, code_challenge) {
        println!("the server will accept this!");
    } else {
        println!("something has gone wrong");
    }
}
```

--------------------------------

### Example Usage of PKCE Functions in Rust

Source: https://oauth.iracing.com/oauth2/book/pkce_overview

Demonstrates how to use the `code_verifier`, `code_challenge`, and `is_valid` functions in a `main` function. It generates a verifier and challenge, then validates them, printing the results. It also shows how to manually set verifier and challenge values for testing.

```rust
use base64::prelude::{Engine, BASE64_URL_SAFE_NO_PAD};
use rand::{thread_rng, Rng};
use regex::Regex;
use sha2::{Digest, Sha256};
// This code is demonstrative, not performant.
// These are the characters that can be accepted as part of
// a code verifier.  They are being stored as a byte array.
const CHARS: &[u8] = b"\
ABCDEFGHIJKLMNOPQRSTUVWXYZ\
abcdefghijklmnopqrstuvwxyz\
1234567890-._~uyền";
/// Generate a code verifier of the given length.
///
/// # Panics
///
/// This code panics if the length is less than
/// 43 or greater than 128.
fn code_verifier(len: usize) -> String {
    assert!(len >= 43);
    assert!(len <= 128);
    // Use a cryptographically strong random number generator.
    let mut rng = thread_rng();
    (0..len) // for each in 0 to len exclusive
        .into_iter() // iterate
        .map(|_| rng.gen_range(0..CHARS.len())) // get an index into CHARS
        .map(|i| CHARS[i]) // get the byte at the index
        .map(char::from) // map it back to a character
        .collect() // collect the characters into a String
}
/// Generate a code challenge for the given verifier.
///
/// # Panics
///
/// This code panics if the given code verifier is less
/// than 43 characters long or greater than 128 characters.
fn code_challenge(code_verifier: String) -> String {
    assert!(code_verifier.len() >= 43);
    assert!(code_verifier.len() <= 128);
    code_verifier
        .chars() // get the characters in the String
        .for_each(|c| { // for each character
            assert!(CHARS.contains(&(c as u8))); // check that it is valid
        });
    // Prepare a SHA256 hash.
    let mut sha256 = Sha256::new();
    // Update the hash with the verifier.
    sha256.update(code_verifier);
    // Compute the final hash.
    let result = sha256.finalize();
    // Encode it as base64.
    let base64 = base64::engine::general_purpose::STANDARD.encode(&result[..]);
    // Make the base64 encoding "URL Safe" and remove the padding.
    base64
        .chars() // get the characters
        .filter_map(|c| match c {
            '=' => None,      // remove padding
            '+' => Some('-'), // make URL Safe
            '/' => Some('_'), // make URL Safe
            x => Some(x),     // return anything else untouched
        })
        .collect() // collect it into a String
}
/// Validate a code verifier and challenge pair.
/// The value `true` is returned when valid.
///
/// This is another way of writing the `code_challenge` function.
fn is_valid(code_verifier: String, code_challenge: String) -> bool {
    let re = Regex::new(r"^[A-Za-z0-9_\.\-~]{43,128}").unwrap();
    if !re.is_match(&code_verifier) {
        return false;
    }
    let digest = Sha256::digest(code_verifier.as_bytes());
    let encoded = BASE64_URL_SAFE_NO_PAD.encode(digest);
    // If the given verifier matches the challenge, the server
    // will accept the pair.
    encoded == code_challenge
}
fn main() {
    /// Prefer the maximum.
    let code_verifier = code_verifier(128);
    // Override it with your own by uncommenting the following
    // and replacing the contents of the string:
    // let code_verifier = "5-Giz4oGgbRTt2Q2VmhQMKw_aTp9UJCQuD_~ZAlP-QM".to_string();
    println!("code_verifier: {code_verifier}");
    let code_challenge = code_challenge(code_verifier.clone());
    // Override it with your own by uncommenting the following
    // and replacing the contents of the string:
    //let code_challenge = "-FG7uN-lx34GXN3xvKEPcwqoYnGX2R4ACX59z_X28vE".to_string();
    println!("code_challenge: {code_challenge}");
    if is_valid(code_verifier, code_challenge) {
        println!("the server will accept this!");
    } else {
        println!("something has gone wrong");
    }
}
```

--------------------------------

### HTTP POST Request Example

Source: https://oauth.iracing.com/oauth2/book/reading_this_book

Demonstrates a standard HTTP POST request format, including the request line, host, authorization, content type, and body. Parameters are sent in the body, typically as `application/x-www-form-urlencoded`.

```http
POST /oauth2/other/endpoint HTTP/1.1
Host: oauth.iracing.com
Authorization: Bearer ...elided...
Content-Type: application/x-www-form-urlencoded

example=true&another=false
```

--------------------------------

### HTTP Redirect Response Example

Source: https://oauth.iracing.com/oauth2/book/reading_this_book

Shows the full HTTP wire format for a temporary redirect response. This includes the status code (307) and a `Location` header specifying the new URL.

```http
HTTP/1.1 307 Temporary Redirect
Location: https://localhost/some/endpoint?example=true&another=false
```

--------------------------------

### JSON Response Example

Source: https://oauth.iracing.com/oauth2/book/reading_this_book

Illustrates a typical JSON response body format used by the API when data is returned. It assumes a 200 OK HTTP status code.

```json
{
  "example": true,
  "another": false
}
```

--------------------------------

### POST /oauth2/other/endpoint

Source: https://oauth.iracing.com/oauth2/book/print

An example of a typical HTTP POST request to an OAuth 2.0 endpoint. This includes common headers like Host, Authorization, and Content-Type, along with a URL-encoded form data body.

```APIDOC
## POST /oauth2/other/endpoint

### Description
This endpoint handles POST requests, typically used for submitting form data or performing actions that modify server state. Parameters are sent in the request body.

### Method
POST

### Endpoint
`/oauth2/other/endpoint`

### Parameters
#### Query Parameters
None specified in the example.

#### Request Body
- **example** (boolean) - Indicates an example parameter, expected to be true.
- **another** (boolean) - Indicates another parameter, expected to be false.

### Request Example
```
POST /oauth2/other/endpoint HTTP/1.1
Host: oauth.iracing.com
Authorization: Bearer ...elided...
Content-Type: application/x-www-form-urlencoded

example=true&another=false
```

### Response
#### Success Response (200)
- **example** (boolean) - The example parameter value.
- **another** (boolean) - The another parameter value.

#### Response Example
```json
{
  "example": true,
  "another": false
}
```

#### Other Responses
- **307 Temporary Redirect**: May occur, redirecting to a new URL with parameters in the query string.
```

--------------------------------

### GET iRacing User Profile with OAuth2

Source: https://oauth.iracing.com/oauth2/book/iracing_profile_endpoint

This endpoint retrieves basic profile information for an iRacing user. It requires an OAuth2 access token with the 'iracing.profile' scope. The request is a simple GET request to the specified URL, and it returns a JSON object containing the user's name and customer ID.

```HTTP
GET https://oauth.iracing.com/oauth2/iracing/profile HTTP/1.1
Authorization: Bearer ...elided...
```

```JSON
{
  "iracing_name": "John West",
  "iracing_cust_id": 15535
}
```

--------------------------------

### Accessing Protected Resources

Source: https://oauth.iracing.com/oauth2/book/auth_overview

Demonstrates how to use the obtained access token to make authenticated requests to resource servers.

```APIDOC
## Accessing Resource Servers

### Description
Access tokens are used to authenticate requests to resource servers. The access token is included in the `Authorization` header.

### Method
GET (or other HTTP methods as applicable)

### Endpoint
[Resource Server Endpoint]

### Headers
- **Authorization** (string) - Required - The access token prefixed with `Bearer `.

### Request Example
```
GET /api/resource
Authorization: Bearer ACCESS_TOKEN
```

### Response
#### Success Response (200 OK)
- The response from the resource server.

#### Response Example
```json
{
  "data": "Protected resource information"
}
```
```

--------------------------------

### Generate PKCE Code Challenge from Verifier in Rust

Source: https://oauth.iracing.com/oauth2/book/print

Creates a PKCE code challenge by SHA256 hashing the provided code verifier and then Base64 URL encoding the result, removing padding. It also validates that the verifier string contains only allowed characters. Panics if the verifier is not between 43 and 128 characters.

```rust
use base64::prelude::{Engine, BASE64_URL_SAFE_NO_PAD};
use rand::{thread_rng, Rng};
use regex::Regex;
use sha2::{Digest, Sha256};

// This code is demonstrative, not performant.
// These are the characters that can be accepted as part of
// a code verifier.  They are being stored as a byte array.
const CHARS: &[u8] = b"\ABCDEFGHIJKLMNOPQRSTUVWXYZ\abcdefghijklmnopqrstuvwxyz\1234567890-._~";

/// Generate a code challenge for the given verifier.
///
/// # Panics
///
/// This code panics if the given code verifier is less
/// than 43 characters long or greater than 128 characters.
fn code_challenge(code_verifier: String) -> String {
    assert!(code_verifier.len() >= 43);
    assert!(code_verifier.len() <= 128);
    code_verifier
        .chars() // get the characters in the String
        .for_each(|c| { // for each character
            assert!(CHARS.contains(&(c as u8))); // check that it is valid
        });
    // Prepare a SHA256 hash.
    let mut sha256 = Sha256::new();
    // Update the hash with the verifier.
    sha256.update(code_verifier);
    // Compute the final hash.
    let result = sha256.finalize();
    // Encode it as base64.
    let base64 = base64::engine::general_purpose::STANDARD.encode(&result[..]);
    // Make the base64 encoding "URL Safe" and remove the padding.
    base64
        .chars() // get the characters
        .filter_map(|c| match c {
            '=' => None,      // remove padding
            '+' => Some('-'), // make URL Safe
            '/' => Some('_'), // make URL Safe
            x => Some(x),     // return anything else untouched
        })
        .collect() // collect it into a String
}
```

--------------------------------

### GET /oauth2/sessions

Source: https://oauth.iracing.com/oauth2/book/sessions_endpoint

Retrieves a list of sessions for the authenticated user. Only sessions associated with the calling client are returned.

```APIDOC
## GET /oauth2/sessions

### Description
Retrieves a list of sessions for the authenticated user. Only sessions associated with the calling client are returned.

### Method
GET

### Endpoint
https://oauth.iracing.com/oauth2/sessions

### Parameters
This endpoint has no parameters.

### Request Example
```json
{
  "example": "GET /oauth2/sessions HTTP/1.1\nHost: oauth.iracing.com\nAuthorization: Bearer ...elided..."
}
```

### Response
#### Success Response (200)
- **sessions** (array) - A list of session objects detailing the user’s sessions.
  - **session_id** (string) - Unique identifier for the session.
  - **client_id** (string) - Identifier of the client associated with the session.
  - **client_name** (string) - Name of the client.
  - **client_developer_name** (string) - Name of the client's developer.
  - **client_developer_url** (string) - URL of the client's developer.
  - **client_developer_email** (string) - Email of the client's developer.
  - **scope** (string) - The scope granted to the session.
  - **scope_descriptions** (array of strings) - Descriptions of the granted scopes.
  - **auth_time** (integer) - Timestamp of when the authentication occurred.
  - **last_activity** (integer) - Timestamp of the last activity in the session.
  - **session_expiration** (integer) - Timestamp when the session will expire.
  - **current_session** (boolean) - Indicates if this is the current active session.
  - **impersonated** (boolean) - Indicates if the session is impersonated.
  - **impersonation_note** (string) - A note explaining the impersonation, if applicable.
  - **first_ip** (string) - The IP address from which the session was first initiated.
  - **first_continent** (string) - The continent of the first IP address.
  - **first_country** (string) - The country of the first IP address.
  - **first_subdivisions** (array of strings) - Geographic subdivisions (e.g., state, province) of the first IP address.
  - **first_city** (string) - The city of the first IP address.
  - **first_user_agent_header** (string) - The User-Agent header from the first request.
  - **first_user_agent_operating_system** (string) - The operating system detected from the first User-Agent.
  - **first_user_agent_browser** (string) - The browser detected from the first User-Agent.
  - **last_ip** (string) - The IP address of the last activity in the session.
  - **last_continent** (string) - The continent of the last IP address.
  - **last_country** (string) - The country of the last IP address.
  - **last_subdivisions** (array of strings) - Geographic subdivisions (e.g., state, province) of the last IP address.
  - **last_city** (string) - The city of the last IP address.
  - **last_user_agent_header** (string) - The User-Agent header from the last request.
  - **last_user_agent_operating_system** (string) - The operating system detected from the last User-Agent.
  - **last_user_agent_browser** (string) - The browser detected from the last User-Agent.

#### Response Example
```json
{
  "sessions": [
    {
      "session_id": "336995c9-67bd-4e5c-aa93-0d5e75c463d9",
      "client_id": "client_identifier",
      "client_name": "Client Name",
      "client_developer_name": "Client Developer Name",
      "client_developer_url": "http://localhost/",
      "client_developer_email": "root@localhost",
      "scope": "sessions",
      "scope_descriptions": ["Session management."],
      "auth_time": 1680276758,
      "last_activity": 1680276828,
      "session_expiration": 1680309158,
      "current_session": true,
      "impersonated": true,
      "impersonation_note": "support for login test; approved by cust in #123456",
      "first_ip": "192.168.23.103",
      "first_continent": "North America",
      "first_country": "United States",
      "first_subdivisions": ["Massachusetts"],
      "first_city": "Chelmsford",
      "first_user_agent_header": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
      "first_user_agent_operating_system": "Linux",
      "first_user_agent_browser": "Chrome",
      "last_ip": "192.168.23.103",
      "last_continent": "North America",
      "last_country": "United States",
      "last_subdivisions": ["Massachusetts"],
      "last_city": "Chelmsford",
      "last_user_agent_header": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
      "last_user_agent_operating_system": "Linux",
      "last_user_agent_browser": "Chrome"
    }
  ]
}
```
```

--------------------------------

### Generate PKCE Code Challenge from Verifier in Rust

Source: https://oauth.iracing.com/oauth2/book/pkce_overview

Creates a PKCE code challenge from a given code verifier. It first hashes the verifier using SHA256 and then encodes the hash using URL-safe base64 without padding. The input verifier must be between 43 and 128 characters and contain only valid characters.

```rust
use base64::prelude::{Engine, BASE64_URL_SAFE_NO_PAD};
use rand::{thread_rng, Rng};
use regex::Regex;
use sha2::{Digest, Sha256};
// This code is demonstrative, not performant.
// These are the characters that can be accepted as part of
// a code verifier.  They are being stored as a byte array.
const CHARS: &[u8] = b"\
ABCDEFGHIJKLMNOPQRSTUVWXYZ\
abcdefghijklmnopqrstuvwxyz\
1234567890-._~uyền";
/// Generate a code challenge for the given verifier.
///
/// # Panics
///
/// This code panics if the given code verifier is less
/// than 43 characters long or greater than 128 characters.
fn code_challenge(code_verifier: String) -> String {
    assert!(code_verifier.len() >= 43);
    assert!(code_verifier.len() <= 128);
    code_verifier
        .chars() // get the characters in the String
        .for_each(|c| { // for each character
            assert!(CHARS.contains(&(c as u8))); // check that it is valid
        });
    // Prepare a SHA256 hash.
    let mut sha256 = Sha256::new();
    // Update the hash with the verifier.
    sha256.update(code_verifier);
    // Compute the final hash.
    let result = sha256.finalize();
    // Encode it as base64.
    let base64 = base64::engine::general_purpose::STANDARD.encode(&result[..]);
    // Make the base64 encoding "URL Safe" and remove the padding.
    base64
        .chars() // get the characters
        .filter_map(|c| match c {
            '=' => None,      // remove padding
            '+' => Some('-'), // make URL Safe
            '/' => Some('_'), // make URL Safe
            x => Some(x),     // return anything else untouched
        })
        .collect() // collect it into a String
}
```

--------------------------------

### GET /oauth2/iracing/profile

Source: https://oauth.iracing.com/oauth2/book/iracing_profile_endpoint

Retrieves basic profile information for an iRacing user if the client has been granted the 'iracing.profile' scope. This endpoint is used for identity verification purposes.

```APIDOC
## GET /oauth2/iracing/profile

### Description
Retrieves basic profile information for an iRacing user. This is useful for identity verification when a client has been granted the `iracing.profile` scope.

### Method
GET

### Endpoint
`https://oauth.iracing.com/oauth2/iracing/profile`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
GET https://oauth.iracing.com/oauth2/iracing/profile HTTP/1.1
Authorization: Bearer ...elided...
```

### Response
#### Success Response (200)
Returns an `application/json` object containing the user's iRacing name and customer ID.
- **iracing_name** (string) - The name of the user.
- **iracing_cust_id** (integer) - The numeric customer identifier of the user.

#### Response Example
```json
{
  "iracing_name": "John West",
  "iracing_cust_id": 15535
}
```
```

--------------------------------

### Specific Error Explanations

Source: https://oauth.iracing.com/oauth2/book/print

Detailed explanations for common OAuth 2.0 error conditions.

```APIDOC
## Specific Error Explanations

### access_denied / unauthorized_client

#### Description
Indicates that the server or end-user denied an otherwise valid request. This is opposed to `unauthorized_client` which signals a problem with how the client is attempting to use the server.

#### Common Causes
* The session has expired, become invalid, or no longer exists.
* The user denied the client's scope request.
* The supplied credentials were not correct.
* A request was made for a resource disallowed to the user.

### insufficient_scope

#### Description
The scope of the access token does not include authorization for the requested resource. Some operations require end-user delegation captured as the scope of the access token.

#### Resolution
An access token cannot gain new privileges; a new access token must be obtained before the operation can proceed.

### invalid_client

#### Description
Client authentication failed. Clients are authenticated by specific parameter values, and one or more of these mechanisms were incorrect.

#### Common Causes
* The `client_id` is not valid.
* The `redirect_uri` does not match exactly.
* The `client_secret` (if issued) is incorrect.

> **Note:** The `redirect_uri` and `client_secret` should be URL (percent) encoded when submitting them to `/token`. Additionally, the `client_secret` must be properly masked before it is URL encoded.

### invalid_grant

#### Description
The provided authorization code or refresh token is invalid. The client attempted to use a `code` or `refresh_token` with `/token` which the server rejected.

#### Resolution
The `code` or `refresh_token` should be discarded. This error occurs when:
* A token or session has become invalid or was revoked.
* PKCE verification fails.
* A request is made that needs stronger authentication.
* A subscription is made inactive.

### invalid_request

#### Description
The request was malformed in some way. This includes invalid parameter values, repeated parameters, parsing errors, or other such issues.
```

--------------------------------

### Sessions API

Source: https://oauth.iracing.com/oauth2/book/sessions_overview

Enumerates the client sessions for the user.

```APIDOC
## GET /sessions

### Description
Enumerates the client sessions for the user.

### Method
GET

### Endpoint
/sessions

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **sessions** (array) - A list of connected client sessions.
  - **session_id** (string) - The unique identifier for the session.
  - **client_name** (string) - The name of the client associated with the session.
  - **created_at** (string) - The timestamp when the session was created.

#### Response Example
```json
{
  "sessions": [
    {
      "session_id": "abc123xyz789",
      "client_name": "Example App",
      "created_at": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### iRacing OAuth2 Auth Service Error Handling

Source: https://oauth.iracing.com/oauth2/book/errors

This section details how the iRacing.com Auth Service handles errors, differentiating between identified and unidentified clients. It provides examples of error responses for both scenarios and lists common error codes.

```APIDOC
## iRacing.com Auth Service Error Handling

Unless otherwise specified, errors from this server are returned either as a redirect or as an `application/json` object in the response body.

### Error Handling for Identified Clients

If the server can validate the identity of the client, the server will return errors by redirecting to the `redirect_uri` with details.

#### Example Redirect Error Response
```http
HTTP/1.1 302 Found
Location: https://registered-app.com/callback?error=unsupported_response_type&error_description=Response%20type%20test%20not%20supported.&error_uri=https%3A%2F%2Foauth.iracing.com%2Foauth2%2Fbook%2Ferror_unsupported_response_type.html&state=...client_state_data...
```

**Parameters in Redirect:**
* `error` (string) - A single ASCII error code.
* `error_description` (string) - A textual description of the error.
* `error_uri` (string) - A link to documentation.
* `state` (string, optional) - The unmodified `state` from the `/authorize` call.

### Error Handling for Unidentified Clients

If the server cannot identify the client, the server will return errors as an `application/json` object in the response body.

#### Example JSON Error Response
```json
{
  "status": 400,
  "status_reason": "Bad Request",
  "error": "invalid_request",
  "error_description": "client_id missing",
  "error_uri": "https://oauth.iracing.com/oauth2/book/errors.html"
}
```

**Fields in JSON Response:**
* `status` (integer) - The HTTP status code.
* `status_reason` (string) - A textual representation of the HTTP status code.
* `error` (string) - A single ASCII error code.
* `error_description` (string) - A textual description of the error.
* `error_uri` (string) - A link to documentation.

### Common Error Codes

The `error` codes and their corresponding status codes are:

| error                     | status | status_reason        | notes |
| ------------------------- | ------ | -------------------- | ----- |
| access_denied             | 401    | Unauthorized         |       |
| insufficient_scope        | 403    | Forbidden            | 2     |
| invalid_client          | 403    | Unauthorized         |       |
| invalid_grant           | 400    | Bad Request          |       |
| invalid_request         | 400    | Bad Request          |       |
| invalid_scope           | 400    | Bad Request          |       |
| invalid_token           | 401    | Unauthorized         | 2     |
| server_error            | 500    | Internal Server Error| 1     |
| temporarily_unavailable | 503    | Service Unavailable  | 1     |
| unauthorized_client     | 401    | Unauthorized         |       |
| unsupported_grant_type  | 400    | Bad Request          |       |
| unsupported_response_type | 400    | Bad Request          |       |

**Notes:**
1. This error may be returned by `/token`. This is an extension to the OAuth 2.0 Specification as described in the errata.
2. This error will not be returned by either `/authorize` or `/token`. This is an extension to the OAuth 2.0 Specification for use with other endpoints.
```

--------------------------------

### Initiate Authentication Flow

Source: https://oauth.iracing.com/oauth2/book/authorize_endpoint

To begin an authentication and authorization flow, the client should direct the user's browser to the /authorize endpoint. This endpoint facilitates the OAuth2 authorization code grant flow.

```APIDOC
## GET /oauth2/authorize

### Description
Initiates an OAuth2 authorization code grant flow by redirecting the user's browser to this endpoint.

### Method
GET

### Endpoint
`https://oauth.iracing.com/oauth2/authorize`

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The client identifier issued during client registration.
- **redirect_uri** (string) - Required - A redirect URI registered to the client, which must match exactly.
- **response_type** (string) - Required - The only valid value for this is `code`.
- **code_challenge** (string) - Recommended - A PKCE code challenge. Required for clients that cannot keep a secret, and recommended for server-side applications.
- **code_challenge_method** (string) - Optional - Defaults to `plain`. The PKCE code challenge method. Either `S256` (recommended) or `plain`.
- **state** (string) - Optional - Recommended - This state value will be returned unmodified at the end of the flow. Used for storing request-specific data and CSRF prevention.
- **scope** (string) - Optional - One or more scopes to request, separated by white space. The server may add or remove scopes at its discretion.
- **prompt** (string) - Optional - Space-delimited, case-sensitive list of ASCII string values which influence how the authorization server interacts with the user. Accepted value: "verify".

### Response
#### Success Response (302 Found)
- **Location** (string) - The redirect URI with added query parameters.

#### Response Example
```
HTTP/1.1 302 Found
Location: https://registered-app.com/callback?code=3122eb8a-7a91-4dae-b174-07df2b083913&state=...client_state_data...
```

#### Response Parameters (in redirect URI query string)
- **code** (string) - The authorization code which may be used with the /token endpoint. The value is considered opaque and its format may change.
- **state** (string) - If a `state` value was provided in the initial request, it will be returned unmodified.
```

--------------------------------

### Retrieve User Sessions (HTTP)

Source: https://oauth.iracing.com/oauth2/book/sessions_endpoint

This snippet demonstrates how to make an HTTP GET request to the iRacing OAuth2 sessions endpoint. It requires an Authorization header with a Bearer token. The response is a JSON object containing a list of the user's sessions.

```http
GET https://oauth.iracing.com/oauth2/sessions HTTP/1.1
Authorization: Bearer ...elided...
```

--------------------------------

### Initiate OAuth2 Authorization Request

Source: https://oauth.iracing.com/oauth2/book/authorize_endpoint

Clients should direct the user's browser to the /authorize endpoint to begin the OAuth2 authentication and authorization flow. This request includes parameters like client_id, redirect_uri, response_type, and optionally PKCE parameters and state.

```http
GET https://oauth.iracing.com/oauth2/authorize?client_id=as_issued&redirect_uri=https%3A%2F%2Fregistered-app.com%2Fcallback&response_type=code&code_challenge=...elided...&code_challenge_method=S256&state=...client_state_data...&scope=iracing.auth HTTP/1.1
```

--------------------------------

### OAuth2 Authorization Flow

Source: https://oauth.iracing.com/oauth2/book/auth_overview

Initiates the OAuth2 authorization flow by directing the user's browser to the /authorize endpoint. Clients must specify a redirect_uri for the callback.

```APIDOC
## GET /authorize

### Description
Starts the OAuth2 authorization flow. The user's browser is redirected to this endpoint to grant permissions.

### Method
GET

### Endpoint
/authorize

### Parameters
#### Query Parameters
- **redirect_uri** (string) - Required - The URI to redirect the user back to after authorization.
- **client_id** (string) - Required - The client identifier.
- **scope** (string) - Optional - The scope of the requested permissions.
- **response_type** (string) - Required - Must be 'code' for this flow.

### Request Example
```
GET /authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=read
```

### Response
#### Success Response (302 Found)
Redirects the user's browser to the specified `redirect_uri` with either an authorization `code` or an error parameter in the query string.

#### Response Example
```
HTTP/1.1 302 Found
Location: YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE
```
```

--------------------------------

### Rust Masking Implementation

Source: https://oauth.iracing.com/oauth2/book/print

Provides the Rust implementation of the masking function used for OAuth2 credentials.

```APIDOC
## Rust Masking Implementation

### Description
This function masks a given secret (client secret or user password) using the provided identifier (client ID or username) via SHA-256 hashing and Base64 encoding.

### Method
Rust Function

### Endpoint
N/A (Library Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use base64::prelude::BASE64_STANDARD;
use sha2::{Digest, Sha256};

fn mask(secret: &str, id: &str) -> String {
    let mut hasher = Sha256::new();
    let normalized_id = id.trim().to_lowercase();
    hasher.update(format!("{secret}{normalized_id}"));
    BASE64_STANDARD.encode(hasher.finalize())
}

let secret = "Anagram-tactics-FOOTING-OPACITY-SHONE-keenly";
let id = " John.West@iracing.com ";
let masked = mask(secret, id);
println!("{masked}");
```

### Response
#### Success Response (200)
- **String** - The base64 encoded SHA-256 hash of the concatenated secret and normalized identifier.
```

--------------------------------

### Generate PKCE Code Verifier in Rust

Source: https://oauth.iracing.com/oauth2/book/pkce_overview

Generates a cryptographically secure random string to be used as a code verifier. The length must be between 43 and 128 characters. It uses the `rand` crate for random number generation and a predefined set of characters.

```rust
use base64::prelude::{Engine, BASE64_URL_SAFE_NO_PAD};
use rand::{thread_rng, Rng};
use regex::Regex;
use sha2::{Digest, Sha256};
// This code is demonstrative, not performant.
// These are the characters that can be accepted as part of
// a code verifier.  They are being stored as a byte array.
const CHARS: &[u8] = b"\
ABCDEFGHIJKLMNOPQRSTUVWXYZ\
abcdefghijklmnopqrstuvwxyz\
1234567890-._~uyền";
/// Generate a code verifier of the given length.
///
/// # Panics
///
/// This code panics if the length is less than
/// 43 or greater than 128.
fn code_verifier(len: usize) -> String {
    assert!(len >= 43);
    assert!(len <= 128);
    // Use a cryptographically strong random number generator.
    let mut rng = thread_rng();
    (0..len) // for each in 0 to len exclusive
        .into_iter() // iterate
        .map(|_| rng.gen_range(0..CHARS.len())) // get an index into CHARS
        .map(|i| CHARS[i]) // get the byte at the index
        .map(char::from) // map it back to a character
        .collect() // collect the characters into a String
}
```

--------------------------------

### Generate PKCE Code Verifier in Rust

Source: https://oauth.iracing.com/oauth2/book/print

Generates a random string suitable for a PKCE code verifier, adhering to length constraints (43-128 characters) and character set requirements. It utilizes a cryptographically secure random number generator. Panics if the length is outside the valid range.

```rust
use base64::prelude::{Engine, BASE64_URL_SAFE_NO_PAD};
use rand::{thread_rng, Rng};
use regex::Regex;
use sha2::{Digest, Sha256};

// This code is demonstrative, not performant.
// These are the characters that can be accepted as part of
// a code verifier.  They are being stored as a byte array.
const CHARS: &[u8] = b"\ABCDEFGHIJKLMNOPQRSTUVWXYZ\abcdefghijklmnopqrstuvwxyz\1234567890-._~";

/// Generate a code verifier of the given length.
///
/// # Panics
///
/// This code panics if the length is less than
/// 43 or greater than 128.
fn code_verifier(len: usize) -> String {
    assert!(len >= 43);
    assert!(len <= 128);
    // Use a cryptographically strong random number generator.
    let mut rng = thread_rng();
    (0..len) // for each in 0 to len exclusive
        .into_iter() // iterate
        .map(|_| rng.gen_range(0..CHARS.len())) // get an index into CHARS
        .map(|i| CHARS[i]) // get the byte at the index
        .map(char::from) // map it back to a character
        .collect() // collect the characters into a String
}
```

--------------------------------

### Redirect URI Rules

Source: https://oauth.iracing.com/oauth2/book/print

Guidelines for registering and using Redirect URIs for OAuth2 authentication with iRacing.

```APIDOC
## Redirect URI Rules

### Description

This section outlines the strict requirements and best practices for configuring Redirect URIs for the iRacing OAuth2 authentication flow. Adhering to these rules ensures secure and reliable callback mechanisms for your application.

### General Rules

1.  **Exact Match**: Redirect URIs must match exactly, including query parameters and port numbers, as registered. Any deviation will result in an error.
2.  **Minimum Slashes**: A valid Redirect URI must contain at least three slashes (e.g., `https://app.yourdomain.example/`).
3.  **HTTPS Preference**: The `https://` scheme is strongly preferred. `http://` may require additional justification.
4.  **Custom Schemes**: Custom URL schemes (e.g., `my_iracing_app://`) are supported for mobile applications. Reversed domain names are preferred (e.g., `example.yourdomain.app://`).
5.  **Hostname Preference**: Hostnames are preferred over IP addresses, except for `localhost` where `127.0.0.1` or `[::1]` are preferred.
6.  **Port Specification**: Port numbers can be specified. If registered with an explicit port, using an implicit port (like default 443 for HTTPS) that differs from the registered one will fail.
7.  **Path Specification**: Any arbitrary path can be used. Preferred paths include `/`, `/callback`, `/redirect`, or `/login`.
8.  **Query Parameters**: Query parameters are allowed but must match exactly. Separate registration is required for URIs with different query parameters.
9.  **No Fragments**: URL fragments (e.g., `#fragment`) are not allowed in Redirect URIs.

### Native Application Redirect URIs

For native applications, the following format is supported:
`http://127.0.0.1:0/callback` or `http://[::1]:0/callback`

1.  **Scheme**: Must be `http://`.
2.  **Host**: Must be the IPv4 (`127.0.0.1`) or IPv6 (`[::1]`) loopback address. `localhost` is not accepted.
3.  **Port**: Must be `0`.
4.  **General Rules**: All other general rules still apply.

### Native Application Flow

1.  Start a web server bound to an ephemeral port on the loopback device.
2.  Wait for a callback in the background.
3.  Initiate the browser with a `/authorize` request, using a `redirect_uri` that substitutes `0` with the ephemeral port (e.g., `http://127.0.0.1:25417/callback`).
4.  After authentication, the browser redirects back to the ephemeral port. Collect `code` and `state`.
5.  Shut down the web server and invoke `/token` to complete the process.
```

--------------------------------

### Validate PKCE Verifier and Challenge Pair in Rust

Source: https://oauth.iracing.com/oauth2/book/print

Validates if a given code verifier and code challenge pair are correct. It re-calculates the challenge from the verifier using SHA256 and Base64 URL encoding, then compares it with the provided challenge. Also includes regex validation for the verifier format. Returns `true` if valid, `false` otherwise.

```rust
use base64::prelude::{Engine, BASE64_URL_SAFE_NO_PAD};
use rand::{thread_rng, Rng};
use regex::Regex;
use sha2::{Digest, Sha256};

// This code is demonstrative, not performant.
// These are the characters that can be accepted as part of
// a code verifier.  They are being stored as a byte array.
const CHARS: &[u8] = b"\ABCDEFGHIJKLMNOPQRSTUVWXYZ\abcdefghijklmnopqrstuvwxyz\1234567890-._~";

/// Validate a code verifier and challenge pair.
/// The value `true` is returned when valid.
///
/// This is another way of writing the `code_challenge` function.
fn is_valid(code_verifier: String, code_challenge: String) -> bool {
    let re = Regex::new(r"^[A-Za-z0-9_\.\-\~]{43,128}$").unwrap();
    if !re.is_match(&code_verifier) {
        return false;
    }
    let digest = Sha256::digest(code_verifier.as_bytes());
    let encoded = BASE64_URL_SAFE_NO_PAD.encode(digest);
    // If the given verifier matches the challenge, the server
    // will accept the pair.
    encoded == code_challenge
}
```
Tokens:
Raw