Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.soundpiece.co/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Soundpiece API uses Bearer token authentication. Every request must include your API key in the Authorization header. 
Authorization: Bearer spk_<your-key>
Keys are issued from your account dashboard. Each key is paired with a webhook signing secret (prefixed whsec_) you can use to verify webhook deliveries. Both the key and the signing secret are shown once at creation — save them somewhere safe.

​
Creating a key

  1. Open your account dashboard and go to Developer → API keys.
  2. Click Create key, give it a label (e.g. production-server), and confirm.
  3. The dashboard shows the key value (spk_…) and webhook signing secret (whsec_…) once. Copy both into your secrets manager immediately — we don’t store the key value and you can’t view it again.
After you close the dialog, we cannot show you the key or signing secret again. If you lose them, revoke the key and create a new one.

​
Using your key

Pass the key as a Bearer token on every request: 
curl --request PUT \
  --url https://api.soundpiece.co/v1/create.new_song \
  --header 'Authorization: Bearer spk_<your-key>' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'
In application code, load the key from an environment variable or secrets manager — never hardcode it:
Python
import os, requests

headers = {"Authorization": f"Bearer {os.environ['SOUNDPIECE_API_KEY']}"}
Node.js
const headers = { Authorization: `Bearer ${process.env.SOUNDPIECE_API_KEY}` };

​
Key scoping

Keys are scoped per account. Every key issued to an account can access every endpoint as that account. There is no per-endpoint or per-resource scoping in V1. You can create as many keys as you want — we recommend a separate key per environment (development, staging, production) and per service that calls the API, so you can revoke a single key without disrupting everything.

​
Rotating a key

You can have as many keys active on an account as you want, so rotation is just create-then-delete:
  1. Create a new key in the dashboard.
  2. Deploy your application with the new key.
  3. When the old key has no more traffic against it, delete it.
All keys keep working until you delete the old one — there’s no cutover window to manage. If you suspect a key has been exposed, rotate immediately.

​
Secret leak detection

Keys are formatted so that automated secret-scanning tools (e.g. GitHub’s secret scanning) can recognise them in committed code. If we detect a leak we’ll email the account owner and recommend immediate rotation. If you receive such an alert, treat the key as compromised: revoke it from the dashboard and create a new one.

​
Authentication errors

If your API key is missing, invalid, or revoked, the API returns 401 Unauthorized: 
{
  "detail": "Missing or invalid Authorization header"
}
See the error reference for the full list of authentication-related responses.

​
Enterprise: IP allowlisting

Enterprise accounts can restrict API key usage to a specific set of IP addresses or CIDR ranges. Requests from non-allowlisted IPs receive a 401 Unauthorized response. Contact your account manager to configure allowlisting.