| name | soundcloud-api-integration |
| description | Integrates applications with the SoundCloud HTTP API using OAuth 2.1, OpenAPI, and developer docs. Use when building SoundCloud API clients, auth flows, uploads, playback, pagination, or debugging API errors. |
SoundCloud API integration
Authoritative sources
Use these; do not invent endpoints or headers:
Core rules
- API base:
https://api.soundcloud.com — token host: https://secure.soundcloud.com
- Auth: OAuth 2.1. Authorization Code flow requires PKCE. Do not use legacy
api.soundcloud.com/oauth2/token.
- API requests:
Authorization: OAuth <access_token> unless the OpenAPI operation specifies otherwise.
- Resource identifiers: Use URNs in path parameters (e.g.
soundcloud:users:948745750, soundcloud:tracks:308946187). Numeric ids are deprecated.
- Tokens: Access tokens expire ~1 hour. Refresh tokens are single-use. Cache tokens; renew with
refresh_token grant instead of repeated client_credentials exchanges.
- Client Credentials limits: 50 tokens / 12h per app, 30 / 1h per IP — cache and refresh.
- Pagination: Prefer
linked_partitioning=true and follow next_href until absent.
- Playback: Use
/tracks/{track_urn}/streams (not legacy /stream). Check access: playable, preview, blocked.
- Rate limits: Back off on
429 (including play-stream quota: 15k / 24h per client_id).
- Secrets: Never hardcode
client_id, client_secret, or tokens — use env vars or a secrets manager.
Auth flow selection
| Flow | Use when |
|---|
| Authorization Code + PKCE | User-delegated access (/me, uploads, private content) |
| Client Credentials | Public resources only (search, resolve, public playback) |
Request template
curl -X GET "https://api.soundcloud.com/ENDPOINT" \
-H "Authorization: OAuth ACCESS_TOKEN" \
-H "accept: application/json; charset=utf-8"
Token exchange (Client Credentials)
curl -X POST "https://secure.soundcloud.com/oauth/token" \
-H "accept: application/json; charset=utf-8" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic BASE64_CLIENT_ID_SECRET" \
--data-urlencode "grant_type=client_credentials"
Error handling
401 — missing or invalid token429 — rate limited; exponential backoff- Consult OpenAPI for per-endpoint requirements
Additional resources
