Authentication

Introduction

The objective of Jamendo OAuth2 is to let users log-in to Jamendo, via third-party applications. During the process, the user decides to grant (or not) some rights to your application, in order to let it read/write data from/to Jamendo on the users behalf.
For the user, such a personal data access mechanism is secure, because the user does not need to use his credentials to authentificate inside of the app. He just needs to log-in on Jamendo as usual and from there he can authorize the app to access his data.
Oauth2 is a widely used IETF standard and Jamendo has fully implemented it following the official specification: http://oauth.net/2/.

Workflow

• A new user of your application does something that requires the use of a Jamendo api method, requiring OAuth2 authentication.
• Your application makes an OAuth2 Authorize request to let the user log-in with his Jamendo credentials and authorize your application to access and/or write personal data on his behalf.
• If the user grants your application the requested rigths, the OAuth2 Authorize request will send you back an Authorization Code.
• Your application can then make an OAuth2 Grant request to exchange the Authorization Code for an Access Token and a Refresh Token.
• With the Access Token, your application will be able to execute Jamend Api requests protected by OAuth2 authentication. This allows your application to perform write actions on the users behalf (ex: /setuser/favorite), or retrieve private user data (ex: /reviews/tracks).
• For security reasons, your will be able to use an Authorization Token for a maximum of 2 hours.
• After those 2 hours, your application will receive an error: 'Your access token has expired'.
• At this stage, to continue the users session, the application has to make a new OAuth2 Grant request, passing the Refresh Token instead of the Authorization Code (which isn't valid anymore). Such request will return a new Access Token (again, valid for 2 hours) and a new Refresh Token.
  Don't forget to overwrite the old Refresh Token by the new one in your application storage.
• At anytime, the user can revoke the permissions he has granted to your application in his Jamendo account preferences panel. This action will invalidate the corresponding Access Token and Refresh Token.

Requirements

• The Redirect Url of your application must be defined in your Jamendo developer account.
• You have to use a OAuth2 compatible client to communicate with our OAuth2 server: it should be based on the draft #31 of the OAuth2 protocol (maybe clients that support newer or older versions of the draft will work too, but this is untested).
• For some requests (like Oauth2 Grant) an SSL POST http method is required, even for those where it is not a requirement it is still recommended.

Which methods need the OAuth2 authentication

The Jamendo api methods protected by the OAuth2 authentication are those which require an access_token parameter, typically all the write methods. Check it out reading the 'Required parameters' information listed on every api method documentation page.

OAuth2 Authorize request (get user 'authorization_code')

Objective:

The objective of such a request is to ask the user if he agrees to grant some rights to your application.
The eventual agreement, will redirect the user to the Jamendo login form, if he is not already logged in.

It's possible to ask permissions for different classes of rights, called 'scopes'. Every api method protected by the OAuth2 authentication requires an 'access_token' parameter. To know wich scope is needed for an api method, read the access_token description of that method. At the moment, all our api methods protected by OAuth2 authentication need the scope named 'music'. The music scope allows your application to write user's music properties (user's playlists, user's favorite tracks/artists/albums, ...)
Some methods like /reviews/tracks, /playlists, or /users, simply read public data, and thus accept but don't require the access_token; such methods don't need any specific scope to be accepted.

In the future, we may add some new api methods requiring different scopes: for example 'private' could authorize to read and write user's private data, and 'publish' could authorize to publish reviews on Jamendo...
To summarize, depending on the permissions needed to implement your application features, you will ask the user to authorize one or more corresponding scopes. Of course, the user will be able to authorize all, none, or just some of them.

How to:

To do an OAuth2 Authorize request, make a GET request to "https://api.jamendo.com/v3.0/oauth/authorize" with the following parameters:

Sample: https://api.jamendo.com/v3.0/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL&state=YOURSTATE

Reponse:

If an error got detected that is related to your client_id or your redirect_uri, json string containing the error will be returned in the http body. If an error gets detected for another parameter, the error will be sent to the redirect url as GET parameters.

Error sample: {"error":"invalid_client", "error_description":"Can't get information about this clientId: Not Found", "error_uri":"URL_TO_HELP_YOU"}

If the request is successful, an authorization 'code' and your 'state' (if defined) get returned to your redirect url as GET parameters.

Success (redirect) sample: http://YOUR_REDIRECT_URL?code=YOUR_AUTHORIZATION_CODE&state=YOUR_STATE

OAuth2 Grant request (get an 'access_token')

Objective:

The main objective of the OAuth2 Grant request is to exchange the authorization code you have received with the OAuth2 Authorize request to get an 'access token'.

How to:

To do an OAuth2 Grant request, make a SSL POST request to "https://api.jamendo.com/v3.0/oauth/grant".
Caution, this request MUST be in SSL to protect your client_secret and the accesses you will receive.
Caution, you must execute this request immediately after having received the authorization token from the OAuth2 Authorize request because the authorization code will expire after 30 seconds. Here are the available parameters:

Reponse:

If an error is detected, a json document containing information about the error is returned in the http response body. In the error response you can also have an error_uri that you might want to follow if you need more help to understand the error or understand how to fix it.

Error sample: {"error":"invalid_grant", "error_description":"Authorization code doesn't exist or is invalid for the client"}

If the request is successful, an "access_token", an "expires_in" (time in seconds for which the access_token is valid), a "refresh_token", the "scope" that has been authorized by the user and the "token_type" (always "bearer" (it indicates how to use your OAuth2 client to make OAuth2 access requests) parameters get returned in the http reponse (json).

Success sample: {"access_token":"YOUR_NEW_ACCESS_TOKEN", "expires_in":7200,"token_type":"bearer", "scope":"music", "refresh_token":"YOUR_REFRESH_TOKEN"}

OAuth2 Grant request (refresh an "access_token")

Objective:

The other objective of the OAuth2 Grant request is to renew an access_token when it has expired.

How to:

To refresh an access_token, make an SSL POST request (this request MUST use SSL to protect your client_secret and the accesses you will receive) to "https://api.jamendo.com/v3.0/oauth/grant" with these parameters:

Reponse:

If an error gets detected, a json string containing the error gets returned in the http reponse body. In the error response you can also have an error_uri that you might want to follow if you need more help to understand the error or understand how to fix it.

Error sample: {"error":"invalid_request", "error_description":"The grant type was not specified in the request"}

If the request is successfull, a NEW "access_token", an "expires_in" (time in seconds for which the access_token is valid) a NEW "refresh_token", the "scope" that has been authorized by the user and the "token_type" (always "bearer" (it indicates how to use your OAuth2 client to make OAuth2 access requests) will get returned in the http reponse body (json string).
Don't forget to overwrite the old "access_token" AND the old "refresh_token" by the new ones in your application storage.

Success sample: {"access_token":"YOUR_NEW_ACCESS_TOKEN", "expires_in":7200, "token_type":"bearer", "scope":"music", "refresh_token":"YOUR_NEW_REFRESH_TOKEN"}