> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/benz206/SpotifyMacroBoard/llms.txt
> Use this file to discover all available pages before exploring further.

# Spotify API integration

> Overview of how the Spotify MacroBoard integrates with the Spotify API through a personal proxy server

## Architecture overview

The Spotify MacroBoard uses a three-tier architecture to communicate with the Spotify API:

```
ESP32 MacroBoard → Personal Server (benzhou.tech) → Spotify Web API
```

This proxy architecture provides several key benefits:

* **Performance**: The personal server caches authentication tokens and handles OAuth flows, eliminating the need for the ESP32 to manage complex authentication
* **Security**: Sensitive credentials (client ID, client secret, refresh tokens) are stored on the server, not hardcoded in the ESP32
* **Simplicity**: The ESP32 only needs to make simple HTTPS GET requests with a password parameter
* **Speed**: Server-side caching and connection pooling significantly reduces response times

## Communication flow

### Control actions

When you press a button on the MacroBoard:

1. ESP32 detects the button press (src/src.ino:381-387)
2. ESP32 sends an HTTPS GET request to `/api/manageState/{password}/{action}`
3. Personal server receives the request and validates the password
4. Personal server makes an authenticated request to Spotify Web API
5. Spotify processes the action (play/pause, skip, volume change, etc.)
6. Server returns a response to the ESP32

### State synchronization

The MacroBoard polls for current playback state every 5 seconds:

1. ESP32 sends a request to `/api/getCurrent/{password}` (src/src.ino:395-398)
2. Personal server queries Spotify's current playback endpoint
3. Server returns JSON with track info, playback state, and album art color
4. ESP32 updates the OLED display and RGB LEDs (src/src.ino:247-289)

<Info>
  The 5-second polling interval (defined by `currentDelay` at src/src.ino:25) balances real-time updates with ESP32 power consumption and API rate limits.
</Info>

## HTTPS certificate authentication

The ESP32 uses certificate-based HTTPS to ensure secure communication with the personal server:

```cpp theme={null}
WiFiClientSecure wifiClient;
wifiClient.setCACert(benzServerCert);
```

The certificate is defined in `SampleCredentials.h` and must match the SSL certificate installed on your personal server. This prevents man-in-the-middle attacks and ensures the ESP32 only communicates with your trusted server.

<Warning>
  If you change your server's SSL certificate, you must update the `benzServerCert` constant in your credentials file and re-upload the code to the ESP32.
</Warning>

## Connection management

The ESP32 maintains a persistent HTTPS connection using HTTP Keep-Alive:

```cpp theme={null}
if (!wifiClient.connected()) {
    if (!wifiClient.connect("benzhou.tech", 443)) {
        // Connection failed - show red LEDs
        for (int i = 0; i < RGB_LED_NUM; i++) LEDs[i] = CRGB::Red;
        FastLED.show();
        return;
    }
}
```

This approach minimizes TLS handshake overhead by reusing the same connection for multiple requests. If the connection drops, the ESP32 automatically reconnects on the next request.

## Error handling

The MacroBoard provides visual feedback for different error conditions:

| LED color | Meaning | Location |
| - | - | - |
| Red | Failed to connect to server | src/src.ino:196, 211 |
| Yellow | Request timeout (>5 seconds) | src/src.ino:225 |
| Orange | Invalid response format | src/src.ino:234 |
| Orange-red | OLED display initialization failed | src/src.ino:65 |

## Password authentication

All API requests include a password parameter defined in your credentials file:

```cpp theme={null}
const String PASSWORD = "your-password-here";
```

The personal server validates this password before forwarding requests to Spotify. This provides basic authentication without requiring OAuth on the ESP32.

<Note>
  The password is sent over HTTPS, so it's encrypted in transit. However, make sure to use a strong, unique password that's different from your Spotify credentials.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Server setup" icon="server" href="/api/server-setup">
    Learn how to set up your personal proxy server
  </Card>

  <Card title="API endpoints" icon="code" href="/api/endpoints">
    Detailed reference for all API endpoints
  </Card>
</CardGroup>