Authentication

API keys are the way to authenticate with the Songpot API.

Getting an API Key

Via the Web UI:

1. Sign in at songpot.ai
2. Click your profile and go to Settings
3. Select the API Keys tab
4. Click Create Key
5. Name your key and select permissions
6. Copy your key

Using Your API Key

Include the key in the X-API-Key header:

curl https://api.songpot.space/api/v1/tracks \
  -H "X-API-Key: songpot_live_YOUR_KEY_HERE"

---

API Key Management

List API Keys

GET /api/v1/api-keys

Rotate API Key

Generate a new key and invalidate the old one:

POST /api/v1/api-keys/{key_id}/rotate

Delete API Key

DELETE /api/v1/api-keys/{key_id}

---

Scopes (Permissions)

When creating an API key, select the scopes you need:

Scope	Description
tracks:read	View and list tracks
tracks:write	Upload, update, delete tracks
search:read	Perform searches
usage:read	View API usage statistics

---

Checking Authentication Status

Verify your authentication is working:

GET /api/v1/usage/current

curl https://api.songpot.space/api/v1/usage/current \
  -H "X-API-Key: YOUR_KEY"

Response:

{
  "tier": "free",
  "requests_this_hour": 5,
  "requests_limit_per_hour": 100,
  "uploads_today": 2,
  "daily_upload_limit": 15
}

---

Error Responses

Invalid API Key

{
  "detail": "Invalid or missing API key"
}

Expired API Key

{
  "detail": "API key has expired"
}

Insufficient Permissions

{
  "detail": "Insufficient permissions. Required scope: tracks:write"
}

---

Security Best Practices

Protect Your Keys

1. Never commit keys to version control

   .gitignore

   .env
   *.key

2. Use environment variables

   .env

   SONGPOT_API_KEY=songpot_live_...

   import os
   api_key = os.environ['SONGPOT_API_KEY']