02 – Authentication

Anyone can read Users, public Tracks and Playlists, and Comments on public Tracks. Reading other resources as well as all write operations are protected and require authentication.

• Basic HTTP Auth
• OAuth
• Setup
• Register your application
• Using OAuth 1.0a
  • Get a request token
  • Ask the user to authorize it
  • Trade the authorized request token for an access token
• Using OAuth 1.0
  • Get a request token
  • Ask the user to authorize it
  • Trade the authorized request token for an access token
• Test the access token
• Use the access token to sign request to protected resources

Basic HTTP Auth

We allow Basic HTTP Auth in our sandbox environment to give easy access to protected resources in the API, without being able to manipulate live data.

$ curl -u joey:hairspray 'http://api.sandbox-soundcloud.com/me'

OAuth

To access protected resources you can authenticate with OAuth, a standard to give third party applications the authority to act on a user’s behalf.
You need to register a client application which is connected to your SoundCloud user account.
We’re working on extending this section of the documentation.
In the meantime you’ll find all the OAuth endpoints you need after you register an application.

If you’re not already familiar with OAuth, please read more on oauth.net where there is also a getting started series.
Subscribing to the OAuth mailing list will keep you updated.

Please be aware that we recommend usage of OAuth 1.0a over 1.0. The 1.0a specification solves a security issue where a session fixation attack could occur but is not supported by all libraries.
If you want to upgrade from 1.0 to 1.0a, you can read Seth Fitszimmon’s comments on the topic

Setup

A short “OAuth Dance” example, using a custom wrapper for the Ruby OAuth GEM and passing the OAuth parameters in the querystring.

You can install the Ruby OAuth GEM with gem install oauth. The wrapper is in the code repository of this project.

When you have a running OAuth setup, you can use the Ruby API Wrapper? to communicate with the SoundCloud API.
h3. Terminology

Endpoints

In the code examples \ denotes a line break inserted for legibility.
So

this_is_a_very_long_line_with_no_natural_place_to_put_a_line_break

becomes

this_is_a_very_long_line_with_no_natural_place_to \
_put_a_line_break

Register your application

I you haven’t registered your application with us yet, do so here.
After registering the application you get a consumer key and a consumer secret. A list of your applications is available here. The key is used to identify your application when making requests to our API and the secret is used to sign the request. Please note that the secret should be kept secret and never sent with the request or exposed in any way. Below is an example, if you want test the API you need to do it with your own key/secret pair.

> client = SC::Client.new('sandbox-soundcloud.com', 'EEi2URUfM97pAAxHTogDpQ',
  'NFYd8T3i4jVKGZ9TMy9LHaBQB3Sh8V5sxBiMeMZBow', 'api.')

To access protected resources the request needs to be signed with the consumer’s secret and an access token secret. Follow the flow below to aquire an access token.

Using OAuth 1.0a

Get a request token

The Consumer identifies itself with a signed request and sets a callback for the request token. The response body contains the request token data.

> client.get_request_token(:oauth_callback => "http://your.example.com/oauth_callback")
  # Request => POST /oauth/request_token? \
    oauth_callback=http%3A%2F%2Fyour.example.com%2Foauth_callback& \
    oauth_nonce=1aQylNEzy7gwCjTzms2qN1igpNnull8MeKq38IURKQ& \
    oauth_signature_method=HMAC-SHA1&oauth_token=& \
    oauth_timestamp=1225818820&oauth_consumer_key=EEi2URUfM97pAAxHTogDpQ& \
    oauth_version=1.0&oauth_signature=%2BVi%2BrOShehNrFf8Ax%2FTbAFrAEys%3D

> client.request_token.token
=> "CMPMuFx1PTUe15nZvzYFw"

This token is now connected to the Consumer, but needs to be authorized by the User.

Ask the User to authorize it

> client.authorize_url
=> "http://soundcloud.com/oauth/authorize?oauth_token=CMPMuFx1PTUe15nZvzYFw

This page shows a dialog where the user can authorize the token or refuse the token access. The user has to be logged in to SoundCloud to do so.

When the token has been authorized and if the request token was assigned a callback parameter the browser is redirected to that url with the request token verifier appended:

http://your.example.com/oauth_callback?oauth_verifier=987013

Doing a GET request to this URL should notify the client application that the token has been authorized, otherwise the user needs to manually give the verifier to the client application.

Trade the authorized request token for an access token

Now the consumer can trade the authorized request token for an access token that will be used for future requests to the API.

> client.get_access_token
  # Request => POST /oauth/access_token? \
    oauth_nonce=rV97AaiYtG7hS3DV9fmYGsXopHhiFfygLoGAMcCYck4& \
    oauth_signature_method=HMAC-SHA1& \
    oauth_verifier=987013& \
    oauth_timestamp=1225819328& \
    oauth_consumer_key=EEi2URUfM97pAAxHTogDpQ& \
    oauth_version=1.0&oauth_signature=Pp1JUAX7P5e1ULJRnmuMZJK5RZ4%3D
> client.access_token.token
=> "fJutKvxpdNJDQoMHvhoDkQ"

Using OAuth 1.0

Get a request token

The Consumer identifies itself with a signed request and receives a request token.

> client.get_request_token
  # Request => POST  /oauth/request_token? \
    oauth_nonce=1aQylNEzy7gwCjTzms2qN1igpNnull8MeKq38IURKQ& \
    oauth_signature_method=HMAC-SHA1&oauth_token=& \
    oauth_timestamp=1225818820&oauth_consumer_key=EEi2URUfM97pAAxHTogDpQ& \
    oauth_version=1.0&oauth_signature=%2BVi%2BrOShehNrFf8Ax%2FTbAFrAEys%3D

> client.request_token.token
=> "CMPMuFx1PTUe15nZvzYFw"

This token is now connected to the Consumer, but needs to be authorized by the User.

Ask the User to authorize it

> client.authorize_url("http://example.com")
=> "http://soundcloud.com/oauth/authorize?oauth_token=CMPMuFx1PTUe15nZvzYFw& \
    oauth_callback=http://example.com"

If you are able to direct a web browser to the url do so, otherwise instruct the user how to get to this url.

This page shows a dialog where the user can authorize the token or refuse the token access. The user has to be logged in to SoundCloud to do so.

When the token has been authorized and if the callback parameter has been set, or the client application was registed with a callback url the browser is redirected to that url with the request token appended:

http://example.com/?oauth_token=CMPMuFx1PTUe15nZvzYFw

Doing a get request to this URL could notify that this token has been authorized, otherwise the user needs to inform the application this.

Trade the authorized request token for an access token

Now the consumer can trade the authorized request token for an access token that will be used for future requests to the API.

> client.get_access_token
  # Request => POST  /oauth/access_token? \
    oauth_nonce=rV97AaiYtG7hS3DV9fmYGsXopHhiFfygLoGAMcCYck4& \
    oauth_signature_method=HMAC-SHA1& \
    oauth_token=CMPMuFx1PTUe15nZvzYFw& \
    oauth_timestamp=1225819328& \
    oauth_consumer_key=EEi2URUfM97pAAxHTogDpQ& \
    oauth_version=1.0&oauth_signature=Pp1JUAX7P5e1ULJRnmuMZJK5RZ4%3D
> client.access_token.token
=> "fJutKvxpdNJDQoMHvhoDkQ"

Test the access token

This is not required but could be nice to do.

> client.test_request_ok?
  # Request => GET  /oauth/test_request? \
    oauth_nonce=PxQHINpbhGzkzkDa0yo63qhb3DSPNFp4yr73h6VyQYg& \
    oauth_signature_method=HMAC-SHA1&oauth_token=fJutKvxpdNJDQoMHvhoDkQ& \
    oauth_timestamp=1225819433&oauth_consumer_key=EEi2URUfM97pAAxHTogDpQ& \
    oauth_version=1.0&oauth_signature=fnarIQENmD5PbyacRrKzu8n6xxQ%3D
=> true

Use the access token to sign request to protected resources

http://api.soundcloud.com/me is a protected resource and can only be accessed when logged in. With our access token we can access this resource and find out who we are.

> res = client.do_request(:get, "/me/")
  # Request => GET  /me/? \
    oauth_nonce=nZhE54oOH9QFXtNzhz7GvCjcWcGB8YSI0YalF9m4pPA& \
    oauth_signature_method=HMAC-SHA1&oauth_token=fJutKvxpdNJDQoMHvhoDkQ& \
    oauth_timestamp=1225819683&oauth_consumer_key=EEi2URUfM97pAAxHTogDpQ& \
    oauth_version=1.0&oauth_signature=M%2Be8V9ZmsHfPVR8NZhvXVQIfhA8%3D
> JSON.parse(res.body)['username']
=> "Hannes"

This means we can act on the behalf of the User that authorized the token. Creating Tracks, making Comments, adding Users to their contact lists and much more.