Skip to main content

​
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. The plaintext is shown once at creation — save it somewhere safe. Webhook signing secrets (prefixed whsec_) used to verify webhook deliveries are a separate resource, also managed from the dashboard. You can rotate one without touching the other.

​
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_…) once. Copy it 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 again. If you lose it, revoke the key and create a new one.

​
Creating a webhook signing secret

If you plan to receive webhooks:
  1. Go to Developer → Webhook signing secrets in the dashboard.
  2. Click Create signing secret, give it a label, and confirm.
  3. The dashboard shows the secret value (whsec_…) once. Save it alongside your API key.
You can create multiple signing secrets — useful during rotation. See secret rotation.

​
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.