README

A PHP class for automated Peloton API OAuth token management. Handles the full authentication lifecycle - login, token refresh, and credential fallback - without requiring an authorised Peloton API endpoint.

Disclaimer: This is an unofficial library with no affiliation with Peloton Interactive, Inc. It uses Peloton's web OAuth PKCE flow, which may change at any time. Use at your own risk and in accordance with Peloton's terms of service.

Features

• Obtains Peloton API OAuth access and refresh tokens from username and password alone
• Automatically refreshes tokens before they expire
• Falls back to full credential login if the refresh token has expired
• Once set up, requires no manual intervention
• No config files - credentials and tokens are passed directly, keeping storage in your control

Requirements

• PHP 7.4 or higher
• cURL extension enabled

Installation

Via Composer

composer require ultra-nick/peloton-auth

Manual

Copy PelotonAuth.php into your project and require_once it directly.

Usage

Basic usage

Instantiate the class with your Peloton credentials and call getTokenData(). That's it - the library handles everything else internally.

require_once 'PelotonAuth.php';

$auth = new PelotonAuth('your@email.com', 'yourpassword');
$tokens = $auth->getTokenData();

echo $tokens->access_token;
echo $tokens->refresh_token;
echo $tokens->user_id;
echo $tokens->expires_at; // Unix timestamp

Persisting tokens between runs

The library manages tokens in memory. To avoid a full login on every run, store the tokens yourself and pass them back in on the next instantiation:

// Load previously stored tokens (from a file, database, etc.)
$stored = json_decode(file_get_contents('tokens.json'));

$auth = new PelotonAuth(
    'your@email.com',
    'yourpassword',
    $stored->access_token  ?? null,
    $stored->refresh_token ?? null
);

$tokens = $auth->getTokenData();

// Save the updated tokens for next time
file_put_contents('tokens.json', json_encode($tokens));

Making API requests

getTokenData() returns the tokens you need to make your own API requests:

$tokens = $auth->getTokenData();

$ch = curl_init('https://api.onepeloton.com/api/me');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $tokens->access_token,
        'Content-Type: application/json',
    ],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);  // Deprecated from PHP 8.5 - safe to remove if running PHP 8.0+

How it works

Peloton's API uses Auth0 for authentication. This library implements the OAuth 2.0 PKCE (Proof Key for Code Exchange) flow - the same flow used by the Peloton web app.

Token lifecycle is managed automatically in three tiers:

1. Valid token - returned immediately with no network call
2. Token expired, refresh token present - silently refreshes using the stored refresh token
3. No tokens, or refresh fails - performs a full PKCE login using the stored credentials

API Reference

Constructor

new PelotonAuth(
    string  $username,
    string  $password,
    ?string $accessToken  = null,
    ?string $refreshToken = null
)

getTokenData(): object

Returns a valid token data object, refreshing or re-authenticating as needed.

$tokens = $auth->getTokenData();

Returns an object with the following properties:

Throws \RuntimeException if all authentication attempts fail.

Security

• Store your credentials and token files outside your web root
• Never commit credentials or token files to version control - add them to .gitignore
• Treat access and refresh tokens with the same care as passwords

Contributing

Issues and pull requests are welcome. If Peloton's API auth flow changes and this library breaks, please open an issue.

License

MIT - see LICENSE for details.