Credential rotation

You can rotate Client ID and Client Secret for a registered API application without deleting the app. Create a new credential pair, deploy the new secrets, then revoke the old pair when traffic has moved over.

Rotation uses the app registration API at https://api-reg.soundcloud.com. These routes are not available on https://api.soundcloud.com. Use the SoundCloud API CLI (recommended) or call the registration API directly with a user OAuth access token from the same sign-in flow as Get an API key.

Limits#

• At most 3 active credentials per application.
• You must keep at least one active credential; you cannot revoke the last one.
• Cloning a credential requires Artist Pro on the application owner account (same as registering an app).
• Revoking a credential does not require Artist Pro.

A cloned credential copies the same redirect URI and settings as the source credential; only the client_id and client_secret change.

Recommended workflow#

1. List credentials — note the client_id you plan to replace.
2. Clone — obtain a new client_id and client_secret.
3. Deploy — update your integration to use the new secrets; confirm OAuth and API calls succeed.
4. Revoke — remove the old credential so the previous secret can no longer be used.

Keep both credentials active briefly during cutover so you can roll back if needed.

CLI commands#

The CLI is maintained in soundcloud/api-public-auth-cli and published as sc-api-auth.mjs. It signs you in (local browser or --remote pairing), then calls the registration API.

List apps (JSON on stdout — one entry per active credential; use client_id to choose which credential to clone or revoke):

curl -fsSL https://raw.githubusercontent.com/soundcloud/api/master/scripts/sc-api-auth.mjs | node --input-type=module - --remote list-apps

Example output (internal URNs are omitted from CLI output; pass --client-id to other commands, not a credentials URN):

[
  {
    "client_id": "1234567890",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://example.com/callback",
    "name": "My App",
    "description": "Internal tool",
    "website": "https://example.com"
  }
]

Clone (prints new credentials on stdout):

curl -fsSL https://raw.githubusercontent.com/soundcloud/api/master/scripts/sc-api-auth.mjs | node --input-type=module - --remote clone --client-id "YOUR_OLD_CLIENT_ID"

If you only have one credential, omit --client-id.

Revoke (confirmation on stderr):

curl -fsSL https://raw.githubusercontent.com/soundcloud/api/master/scripts/sc-api-auth.mjs | node --input-type=module - --remote revoke --client-id "YOUR_OLD_CLIENT_ID"

Use list-apps whenever you have more than one credential or more than one application so you target the correct client_id.

Registration API (advanced)#

All requests use Authorization: OAuth <access_token> (user token from SoundCloud sign-in, not Client Credentials). Base URL: https://api-reg.soundcloud.com.

The path parameter is the credentials URN (for example soundcloud:credentials:456), not the application URN. URL-encode the URN in the path (colons become %3A). When calling the API directly, read the credentials field from each item in GET /me/apps (the CLI uses that value internally but does not print it in list-apps; use --client-id with the CLI instead).

Clone responds with 201 Created and a body containing the new credentials URN, client_id, client_secret, and redirect_uri.

Revoke responds with 204 No Content on success.

Common error responses use the same JSON error shape as app registration (for example max_active_credentials_per_application or cannot_revoke_last_application_credential).

Related topics#

• Get an API key — first-time registration and pairing
• API Guide — Authentication — token exchange after you have credentials
• Update redirect URI — update-redirect subcommand on the same CLI (also via registration API only)