> For the complete documentation index, see [llms.txt](https://form-1.gitbook.io/form-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://form-1.gitbook.io/form-docs/byok-guide.md).

# BYOK Guide (Spotify)

**BYOK = Bring Your Own Key.** To download from Spotify through this API, you register your own Spotify Developer App credentials. The platform does not hold a shared Spotify app on your behalf.

## Why this exists

Spotify's own API terms make a shared, platform-wide credential impractical for a multi-user download API:

* Apps in **Development Mode** are capped at a small number of allowed users (currently 25) — nowhere near enough for a public API with unknown numbers of callers.
* Moving beyond that cap requires Spotify's **Extended Quota** approval, which in practice expects a large existing user base (historically referenced around 250k MAU) — not something a small self-hosted project can realistically obtain.
* Spotify also now requires the app owner's account to have an active Premium subscription for certain API access.

Rather than hit a hard user ceiling or misrepresent the app's usage to Spotify, each API caller uses their **own** Spotify Developer App instead. Your app, your quota, your credentials — the platform only stores them (encrypted) long enough to make API calls on jobs you submit.

{% hint style="info" %}
This only applies to **metadata**. Spotify is never the source of the actual audio — the API matches the track on YouTube Music (via `spotdl`) and downloads from there. Your Spotify credentials are used exclusively to fetch accurate track/artist/album metadata from Spotify's real Web API.
{% endhint %}

## Step 1 — Create a Spotify Developer App

1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) and log in with your own Spotify account.
2. Click **Create app**.
3. Fill in a name and description (anything — this app is only used for API access, not shown to end users). For the redirect URI, any placeholder value like `http://127.0.0.1:8080/callback` works — this API only uses the Client Credentials flow, which doesn't redirect anywhere.
4. Once created, open the app's **Settings** to find your **Client ID** and **Client Secret**.

You now have a `client_id` and `client_secret` that belong to you, under your own Spotify account and quota.

## Step 2 — Register them with the API

```
PUT {{BASE_URL}}/v1/spotify-credentials
```

```bash
curl -X PUT {{BASE_URL}}/v1/spotify-credentials \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_spotify_client_id_here",
    "client_secret": "your_spotify_client_secret_here"
  }'
```

The API validates these live against Spotify before storing anything — if they're wrong, you'll get a `400` explaining why (see [Spotify Credentials](/form-docs/api-reference/spotify-credentials.md) for the full response shapes). Once accepted, your `client_secret` is encrypted at rest and never returned in any future response.

{% hint style="danger" %}
The values above (`your_spotify_client_id_here` / `your_spotify_client_secret_here`) are placeholders. Never paste a real client secret into a shared doc, script committed to version control, or a chat/support thread.
{% endhint %}

## Step 3 — Download

Once registered, `POST /v1/downloads` with `"source": "spotify"` will work using your credentials automatically — you don't pass them again per-request. See [Downloads](/form-docs/api-reference/downloads.md).

If you ever remove your credentials (`DELETE /v1/spotify-credentials`) or they're never registered, Spotify downloads fail fast with a clear `400` rather than queuing a job that can't succeed:

```json
{ "error": "No Spotify credentials registered for this API key. Register yours first via PUT /v1/spotify-credentials." }
```

## FAQ

**Do I need this for SoundCloud or Bandcamp?** No. Only Spotify requires credentials — see [Source-Specific Notes](/form-docs/source-notes.md).

**Can I use the same Spotify Developer App across multiple API keys?** Nothing stops you technically, but each API key stores its own copy of the credentials — register them separately per key.

**What can this Spotify app do with my Spotify account?** Nothing beyond reading public catalog metadata via the Client Credentials flow. It never gets access to your personal library, playlists, or an OAuth user token — it's app-level metadata access only.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://form-1.gitbook.io/form-docs/byok-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.