Documentation‎ > ‎

Authentication

IMPORTANT! OAuth1 has been deprecated to access the Mendeley API.  Current applications using OAuth1 can continue to use it but they will have to migrate to OAuth2 by May 18, 2014

The OpenAPI uses OAuth2 for authentication. Developers must register their application with us before they're able to make use of the API.

You can register your OAuth2 application here. You will have to provide the following information:

  • Application name
  • Redirect URI: This is a required field. The redirect_uri is used for redirecting users back you your application after successful login. Even if your application only uses the Client Credentials Flow for accessing public resources, this field must be specified (e.g. http://localhost).
  • Short description: Please let us know what your awesome application is about!
  • Secret: This is the client secret used for authenticating your application. You can either choose your own or generate one in the page. Please keep it safe. 

Once that's done, you'll be ready to go!

Things to bear in mind when authenticating using OAuth2:

  • To access the API using OAuth2, requests will have to be made to api-oauth2.mendeley.com instead to api.mendeley.com. Requests to the latter will require OAuth1.
  • OAuth2 requires all requests to be sent via a secure connection (HTTPS).


OAuth2 Authorization Flows

Mendeley provides two ways of authentication: for applications accessing resources that require the user's authorization and for applications accessing public data that belongs to Mendeley.

These two flows are known in OAuth2 as Authorization Code and Client Credentials flows. 

Authorization Code Flow

This flow is used for server-side web applications. This flow starts in the user's browser. This flow is used to access user-specific private resources.

1. Requesting an authorization code

Your application will have to send the user to Mendeley's Authorize page to obtain the user's authorization:

https://api-oauth2.mendeley.com/oauth/authorize?client_id=<clientId>&redirect_uri=<redirectUri>&response_type=code&scope=all

You will need to specify the following parameters with the link:

  • client_id: The value provided to you when you registered your application.
  • redirect_uri: The location the user should be returned to after they approved access to your app. It has to be the same value provided when you registered your application.
  • scope: The data your application is requesting access to. For now, just specify 'all'.
  • response_type: 'code' for the server-side application.

2. Exchanging authorization code for an access token

If the request is successful, Mendeley will redirect the user back to your application at the URL specified in redirect_uri. A query parameter code will be included in the redirect. 

The application needs to then exchange the code for an OAuth access token to make API requests. If you are using a library, this step will typically happen automatically. 
If not, you will have to make a request to the token endpoint:

POST https://api-oauth2.mendeley.com/oauth/token

You will need to specify the following parameters in the body of the request: 

  • grant_type: The value 'authorization_code', for the exchange for an access token.
  • code: The code received from the previous step.
  • redirect_uri: The location to return the user to as in the previous request.

IMPORTANT This request needs to be authenticated with the credentials provided at the moment of registration. 
There are two ways of doing this: either by including the Basic Authorization header or by adding the client_id and client_secret in the body of the request.

If the request succeeds, Mendeley will issue and return an OAuth access token in a JSON response with the following values:

  • access_token: The token to do authorized API requests.
  • token_type: Type of token issued, in this case 'bearer'.
  • expires_in: The lifespan of the token, in seconds.
  • refresh_token: This token can be used for reissuing a new access token after the current one has expires.

Refreshing an access token

When the access token is about to expire, it's good to refresh your token before it does to avoid waiting for the API to reject your request because of the invalid token.

To refresh an access token you can do another POST request to the token endpoint specifying refresh_token as the grant_type. 

This request must also be authenticated with client_id and client_secret.

3. Making requests to the API

After obtaining the access token, this can be sent along in a few ways:

     1. Using the Authorization header (preferred): 

  1. GET /oapi/library
    Host: api-oauth2.mendeley.com
    Authorization: Bearer <access_token>
      2. In a query parameter:
  1. GET /oapi/library?access_token=<access_token>
    Host: api-oauth2.mendeley.com
    

The Authorization header presents a few advantages: it is rarely logged by proxy server and access logs, is almost never cached and it doesn't get stored in the browser cache when making requests from the client. However including it as a URL query parameter is useful for debugging since adding the header might be a bit more difficult.

Client Credentials Flow

Accessing the data the public resources of the Mendeley API provide doesn't require user authorization, however, applications still need to be authenticated in our servers. 

For this, just like in the Authorization Code flow step 2, you can request the "anonymous" access token for the application as follows:

POST https://api-oauth2.mendeley.com/oauth/token

You will still need to authenticate the request with client_id and client_secret, as well as providing the grant_type as "client_credentials".

There are different implementations of the OAuth 2.0 protocol available in the net. You can find a good list here and here.


Comments

Developer Forum