Documentation

The flow is initiated by directing the end user in a browser to the SoundCloud authorization endpoint which is https://soundcloud.com/connect. You need to pass several parameters:

• the client_id of your registered app
• a response_type that can either be code or token_and_code (which is a combination of the authorization code and user agent flow)
• a redirect_uri that the user will be redirected to once he accepted or cancelled the flow. This needs to be the same URI that is configured in your app settings.
• a scope=non-expiring which will make sure that the access token is valid forever. If you don't pass this read up on refreshing a token
• optionally a display=popup parameter to optimize the connect screen for popups and mobile.

Example:

https://soundcloud.com/connect?
    scope=non-expiring&client_id=YOUR_CLIENT_ID&
    response_type=code&redirect_uri=http://yourapp.com/soundcloud/oauth-callback

On this page the user will be asked to authorize your app and will be redirected back to your redirect_uri.

If the user declines to authorize your app an error and error_description will be passed as parameter to your redirect_uri:

http://yourapp.com/soundcloud/oauth-callback?
    error=access_denied&error_description=The+end-user+denied+the+request.

If the user authorized your app a code parameter will be passed:

http://yourapp.com/soundcloud/oauth-callback?
    code=0000000EYAA1CRGodSoKJ9WsdhqVQr3g

This code can then be exchanged for an access token via a POST request to:

https://api.soundcloud.com/oauth2/token

Here is an example call:

$ curl -X POST "https://api.soundcloud.com/oauth2/token" \
           -F 'client_id=YOUR_CLIENT_ID' \
           -F 'client_secret=YOUR_CLIENT_SECRET' \
           -F 'grant_type=authorization_code' \
           -F 'redirect_uri=http://yourapp.com/soundcloud/oauth-callback' \
           -F 'code=0000000EYAA1CRGodSoKJ9WsdhqVQr3g'

{
  "access_token": "04u7h-4cc355-70k3n",
  "scope": "non-expiring"
}

Note: Parameters must be sent in the request body, not as part of the query string.

This flow can also be used in desktop and mobile apps by using a custom protocol handler in the redirect_uri which is registered to call your app. For example your-app://callback?code=SOMECODE..

In general we recommend to use Connect with SoundCloud to use this flow.

If you direct the user to:

https://soundcloud.com/connect?
    client_id=YOUR_CLIENT_ID&response_type=token&
    redirect_uri=http://yourapp.com/soundcloud/oauth-callback

The user would return afterwards to:

http://yourapp.com/soundcloud/oauth-callback#access_token=A_VALID_TOKEN&expires_in=3599

You can then extract the access_token directly out of the hash and use it to do authenticated API calls.

With the introduction of Login with Facebook we discourage the use of this flow since a lot of users simply don't have a password set anymore and thus can't use this flow.

The credentials flow allows you to directly exchange a users SoundCloud credentials for an access/refresh token pair. This enables you to provide your own native login form in your app. This flow is not meant for web applications and please make sure that you never store the users passwords.

$ curl -X POST "https://api.soundcloud.com/oauth2/token" \
           -F 'client_id=04u7h-cl13n7-1d' \
           -F 'client_secret=04u7h-cl13n7-53cr37' \
           -F 'grant_type=password' \
           -F 'username=user.name@example.com' \
           -F 'password=p455w0rd'

{
  "access_token": "04u7h-4cc355-70k3n-2",
  "expires_in": 3600,
  "scope": null,
  "refresh_token": "04u7h-r3fr35h-70k3n-2"
}

Note: Parameters must be sent in the request body, not as part of the query string.

Once an access_token is expired you can use the refresh_token to obtain a new one:

$ curl -X POST "https://api.soundcloud.com/oauth2/token" \
           -F 'client_id=YOUR_CLIENT_ID' \
           -F 'client_secret=YOUR_CLIENT_SECRET' \
           -F 'grant_type=refresh_token' \
           -F 'refresh_token=04u7h-r3fr35h-70k3n'

{
  "access_token": "04u7h-4cc355-70k3n-2",
  "expires_in": 3600,
  "scope": null,
  "refresh_token": "04u7h-r3fr35h-70k3n-2"
}

Please note that a refresh_token can only be used once. You have to store and use the refresh_token returned from the refresh request for the next refreshing.

To avoid having to refresh tokens you can request tokens with the scope=non-expiring. This will result in access tokens that never expire.

To make the authentication a bit smoother for the user there is a popup/mobile optimized connect screen. This can be triggered by passing a display=popup in the authorization URL.

For webapps we also created the Connect with SoundCloud SDK that helps you to deal with the popup flow.

It's possible to migrate OAuth 1.0a tokens to OAuth 2 token pairs:

$ curl -X POST "https://api.soundcloud.com/oauth2/token" \
           -F 'client_id=04u7h-cl13n7-1d' \
           -F 'client_secret=04u7h-cl13n7-53cr37' \
           -F 'grant_type=oauth1_token' \
           -F 'refresh_token=OldOAuthToken'

{
  "access_token": "04u7h-4cc355-70k3n-2",
  "expires_in": 3600,
  "scope": null,
  "refresh_token": "04u7h-r3fr35h-70k3n-2"
}

Migrated OAuth 1.0a tokens will not be invalidated.