All Mendeley API requests require authorization credentials to be included with each request. OAuth provides user authentication and authorizes requests.
Remember, your application must be registered with the API to receive values for your OAuth configuration and to be authorized to make API requests.
OAuth 2.0 is used to authorize requests to the Mendeley API. OAuth is a widely adopted, open protocol for users to delegate authorization in a secure manner. OAuth reduces the security risks associated with the more traditional username and password authentication. OAuth is adaptable to many different API client types and defines a number of different client profiles:
OAuth 2.0 client applications can be defined as either confidential or public:
Mendeley uses OAuth access tokens to provide authorization for API requests. A token is a long sequence of characters that contains security credentials. Each token has a limited lifetime and once expired, a replacement token must be generated. Your application will manage the lifecycle of its access tokens and, in series, will:
The API provides three different authorization flows, sometimes referred as grant types, to obtain an access token to suit different client profiles and confidentially abilities.
Each of the three different OAuth authorization flows creates an access token with different abilities and characteristics.
The table below summarizes the abilities and responsibilities of the three provided authorization flows to help you select an appropriate authorization flow for your application.
| Grant type: | Authorization Code | Implicit | Client Credentials |
|---|---|---|---|
| Delegate for: | User | User | Application |
| Client confidentiality required: | Y | Y | |
| Log in user interface required: | Y | Y | |
| Long-lived access tokens: | Y |
Delegation scope determines how much access to Mendeley API resources is permitted. Requests, acting as the delegate for an authenticated Mendeley user, have access to the entire API with read and write manipulation of many key resources. API requests, acting as the delegate for a registered client application, are limited to the read-only Mendeley catalog.
Client confidentiality is not available to all client applications. Most web applications have a private, secure storage location. Secure storage for secrets in desktop and mobile operating systems is often provided to installed native applications. Always ensure your application stores authorization secrets in a secure manner.
Log in user interface must be displayed by client applications when performing API requests on behalf of user. The Mendeley API provides an HTML user interface, optimized for desktop and iOS devices, your application can display in a web panel.
Long-lived access tokens improve the user experience by only requiring the user to authenticate once and provide the ability for your client application to perform scheduled tasks using the API, even when the user is not using the client application.
Once your application has been granted a valid access token, the client can begin authorizing Mendeley API requests. Every request must include the access token and client applications should include the access token value in the HTTP Authorization header.
If your application's environment does not permit modification of the request's Authorization HTTP header, you may include the token value in an HTTP query string appended to the URL. Using the Authorization header is much preferred by Mendeley because HTTP headers are:
Include the token value in the Authorization header field as an HTTP bearer authorization scheme.
GET /files HTTP/1.1
Authorization: Bearer MSwxNDA3Nzc5NzY4ODY5LDEwMzczNDM1MSw3MTQsYWxsLCxpcHB5Q25yMnZtalNTbVpwUEJCVjd1N1VpeWc
Accept: application/vnd.mendeley-file.1+jsonIf your client application can not modify the request's Authorization header, then append the access
token value to the URL using an HTTP query string. Use the field label access_token
include the token's value.
https://api.mendeley.com/documents?access_token=MSwxNDA4MTE2NDQwMDYxLDEwMzczNDM1MSw3MTQsYWxsLCxnbmd6N1NHN2ZMb0lRaWpJX3NMYWJwbE84bkEYour application should URL encode the access token value to protect against any future change away from the current alphanumeric tokens.
Authorization errors can occur for many reasons but common causes are access tokens that are missing, expired, revoked or corrupted. Token error responses include:
WWW-Authenticate HTTP header indicating the class of errorSample response when using an expired token:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mendeley" error="invalid_token"
{
"message": "Could not access resource because: Token has expired"
}Scope errors occur when the access token does not provide the permissions required for the request. A scope error response includes:
A sample response when using a client credential grant type access token to request a user document:
HTTP/1.1 403 Forbidden
Content-Type: application/vnd.mendeley-document.1+json
Content-Length: 60
You do not have the required scopes [all] for this operationWhile the steps outlined above, indicate the tasks required by a client application to authorize an API request, we recommend taking advantage of a library in your application. Many OAuth 2.0 client libraries are available for a wide range of languages and environments.