> 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/api-reference/spotify-credentials.md).

# Spotify Credentials

{% hint style="info" %}
Looking for the simplest way to use ILoveMusic? See the [CLI Guide](/form-docs/cli-guide.md) instead — `ilovemusic download` prompts for your Spotify Client ID/Secret inline the first time you need them and calls this endpoint for you. This page is for developers building their own integration.
{% endhint %}

Manages your **own** Spotify Developer App credentials, used only for Spotify downloads. See the [BYOK Guide](/form-docs/byok-guide.md) for why this exists and how to create the credentials in the first place — this page is the endpoint reference.

Both endpoints require an `X-API-Key` header, and act on the credentials attached to that key only.

## Register or update your credentials

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

### Body

| Field           | Type     | Required |
| --------------- | -------- | -------- |
| `client_id`     | `string` | Yes      |
| `client_secret` | `string` | Yes      |

```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"
  }'
```

{% hint style="danger" %}
Never put a real `client_secret` in a script you commit, share, or paste into a chat. Treat it like a password — it's yours, generated in your own Spotify Developer Dashboard, and the API only ever stores it encrypted.
{% endhint %}

### What happens on submit

The credentials are validated **live against Spotify** before anything is saved — the API fetches a known track's metadata using the client ID/secret you provided. If Spotify rejects them, nothing is stored:

```
400 Bad Request
```

```json
{ "error": "Spotify rejected these credentials: <reason from Spotify>" }
```

If both fields are missing or empty:

```
400 Bad Request
```

```json
{ "error": "'client_id' and 'client_secret' are both required" }
```

If validation succeeds, the secret is encrypted at rest and associated with your API key:

```
200 OK
```

```json
{ "ok": true, "client_id": "your_spotify_client_id_here" }
```

Note that `client_secret` is **never** echoed back — this response is the only confirmation you get that it was saved. If you lose it, you'll need to re-register (Spotify lets you view/regenerate your client secret from your own Developer Dashboard at any time).

Registering new credentials overwrites any previously registered ones for this API key.

## Remove your credentials

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

```bash
curl -X DELETE {{BASE_URL}}/v1/spotify-credentials \
  -H "X-API-Key: YOUR_API_KEY"
```

Clears any stored Spotify credentials for this API key.

```
200 OK
```

```json
{ "ok": true }
```

After this, `POST /v1/downloads` with `source: "spotify"` will fail with the "no Spotify credentials registered" error until you register new ones. SoundCloud and Bandcamp downloads are unaffected — they never used these credentials.


---

# 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/api-reference/spotify-credentials.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.