Authorization code flow is used to obtain an access token to authorize API requests. Authorization code flow is the most flexible of the three supported authorization flows and is the recommended method of obtaining an access token for the API. This authorization flow is best suited to applications that have access to secure, private storage such as web applications deployed on a server. Other authorization flows are available to obtain an access token that may be suitable for your application.
Access tokens, obtained using authorization code flow, provide permissions for your application to manipulate documents and other resources on behalf of a Mendeley user and make requests for all API resources. Access tokens while having a limited lifetime, can be renewed with a refresh token. A refresh token is valid indefinitely and provides ability for your application to schedule tasks on behalf of a user without their interaction.
Your application should warn users they will be asked to authorize using their Mendeley account before initiating an action that requires authorization because users' web browsers will redirect to another site.
Remember, your application must be registered with the API to generate the client application ID, application secret and redirection URL used in the authorization code flow.
The flow for authorization code is:
Your application loads the authorization user interface into a web browser window. The Mendeley OAuth
authorization endpoint is https://api.mendeley.com/oauth/authorize
. Four values must be
passed, contained in an HTTP query string, with the request:
client_id
redirect_uri
response_type
code
indicating the code authorization grant type is
required and an authorization code is desired in the response.scope
all
permitting the manipulation of all API resources.
An optional state
parameter should be included in all requests to protect
against Cross-site request forgery (CSRF) attacks. The state value must be kept secret from the
client and is required later in the access code exchange stage so your application should persist
the value, perhaps in server-side session storage.
state
The completed URL will appear similar to:
https://api.mendeley.com/oauth/authorize?client_id=773&redirect_uri=http:%2F%2Flocalhost%2Fmendeley%2Fserver_sample.php&response_type=code&scope=all&state=213653957730.97845
Use the URL, constructed in the previous step, to ask the user to authorize using their Mendeley credentials. Your application can load, using a GET request, the Authorization page into an existing browser window because the page will be redirected back your application.
The user will be prompted to sign in to Mendeley with their Elsevier credentials if necessary. If they do not have an Elsevier account then they can register for one as part of this flow.
User authentication errors, including incorrect email address or password, are resolved within the authorization process and your application does not have to handle errors for the user. The user can reset their password from the authorization page, solving forgotten password issues.
Incorrect values supplied for client_id
and redirect_uri
do not display the
authentication page and return a response with a 400 Bad Request status code and a JSON object
containing an explanatory message. The user is not redirected back to your
application.
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 90
{"error_message":"Redirection URI does not match the one registered for this application"}
Invalid values for scope
and response_type
are sent to your application's
redirect page. An HTTP query string contains the fields error
and
error_description
indicating the nature of the error.
http://localhost/mendeley/server_sample.php?error=invalid_scope&error_description=Invalid+scope
Your application should report the authorization failure to the user, explain why an error may have occurred and suggest possible solutions.
Once the user has authorized, they are redirected to the page specified in the request's
redirect_uri
query argument. The OAuth service will append an HTTP query string to the
URL containing values for code
and state
(if supplied in the requesting
URL) fields.
http://localhost/mendeley/server_sample.php?state=213653957730.97845&code=zNlyssMxdc8XcKeLdfHvtxmApe
Important: before attempting to use the authorization code, first check the value of
the the state
field. This value must match the value your application supplied
in the URL creation step to protect against CSRF attacks.
Your application now has an authorization code but this can not be used to authorize API requests:
the code must be exchanged for an access token. Extract the value of the code
field and
for use in the next stage.
Your application needs to exchange the authorization code, extracted in the previous stage, for an
OAuth access token to make API requests. The Mendeley OAuth token exchange endpoint is
https://api.mendeley.com/oauth/token
and the exchange is made using an HTTPS request
with the conditions:
grant_type
, code
and redirect_uri
The request is authenticated using HTTP Basic authentication:
username
password
The values sent in the body of the request are:
grant_type
authorization_code
indicating your application is
exchanging an authorization code for an access token.code
redirect_uri
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -u "773:xzcdoG8wmRrf7Npm" -d "grant_type=authorization_code&code=zNlyssMxdc88XcKeLdfHvtxmApe&redirect_uri=http:%2F%2Flocalhost%2Fmendeley%2Fserver_sample.php" https://api.mendeley.com/oauth/token
POST /oauth/token HTTP/1.1
Host: api.mendeley.com
Authorization: Basic NzczOnh6Y2RvRzh3bVJyZjdOcG0=
Content-Type: application/x-www-form-urlencoded
Content-Length: 127
grant_type=authorization_code&code=zNlyssMxdc88XcKeLdfHvtxmApe&redirect_uri=http:%2F%2Flocalhost%2Fmendeley%2Fserver_sample.php
If your application is unable to create or change the HTTP Authorization header, the application
ID and application secret credentials can alternatively be supplied in the body of
the request using the parameters client_id
and client_secret
:
grant_type=authorization_code&code=zNlyssMxdc88XcKeLdfHvtxmApe&redirect_uri=http:%2F%2Flocalhost%2Fmendeley%2Fserver_sample.php&client_id=&773client_secret=zNlyssMxdc88XcKeLdfHvtxmApex
An authorization code can only be exchanged once. Attempting to re-exchange a code will generate a bad request response, outlined below in Error handling.
Authentication errors, including duplicate, incorrect or missing application ID or
application secret, result in an HTTP unauthorized response with a status of
401 Unauthorized
, a WWW‑Authenticate
HTTP header and a plain text
message in the body.
Errors due to incorrect or missing values for grant_type
, code
and
redirect_uri
result in a HTTP bad request response with a status of
400 Bad Request
and a JSON format error code and message:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 82
{"error":"invalid_grant","error_description":"Invalid access code"}
Missing values generate a response with an invalid_request
error code. Invalid values
(including previously used codes) generate a response with an invalid_grant
error code.
Specifying a value other than authorization_code
(or refresh_token
)
generate a response with an unsupported_grant_type
error code.
A successful response from the code exchange request in the previous stage is JSON format data containing the access token. Your application parses the JSON to extract the OAuth access token.
{
"access_token": "MSwxNMWRSemRhbTVVeWYwDA4NDMzY2LDsYWxsLCw0TWtrNEFBNFJoLMSw3NzOTAzZQYWdZeEEEwMzczNDM1",
"expires_in": 3600,
"refresh_token": "MSwxMDM3MzRU3OUMktdmTsZpCDveWT5XMxQOG1SQTtNzczLVUcHOzNADEsbwGFV",
"token_type": "bearer"
}
The JSON data object contains a number of properties in addition to the access token:
access_token
expires_in
refresh_token
token_type
Important: your application must keep the access token and the refresh token secret at all times. Access tokens and refresh tokens should not be visible to any user, including the Mendeley account user.
Access tokens have a lifetime limited to one hour. Using the authorization code flow, access tokens can be renewed without repeated user authorization. The refresh token, obtained in the final step of the access token generation process, encapsulates the user authorization to create new tokens. To obtain a new access token a refresh token request is made.
The request is similar to the authorization code exchange and is made to the same endpoint:
https://api.mendeley.com/oauth/token
. The request:
grant_type
, code
and
redirect_uri
Unlike the code exchange request the body parameters are:
grant_type
refresh_token
indicating your application is refreshing
an access token.refresh_token
redirect_uri
POST /oauth/token HTTP/1.1
Host: api.mendeley.com
Authorization: Basic NzczOnh6Y2RvRzh3bVJyZjdOcG0=
Content-Type: application/x-www-form-urlencoded
Content-Length: 167
grant_type=refresh_token&refresh_token=MSwxMDM3MzRU3OUMktdmTsZpCDveWT5XMxQOG1SQTtNzczLVUcHOzNADEsbwGFV&redirect_uri=http:%2F%2Flocalhost%2Fmendeley%2Fserver_sample.php
A successful refresh response body is JSON data containing the replacement access token. The JSON object contains the same properties as the result of the original access token response.
{
"access_token": "MSwxN1zZPUxsLIzDM1wMJWEdDaTZiNNzMsYLDEdzcXNDY4NzaSzDA4Sw3QWCxFYFBZ0ZWzN3NzMZ3MWp5GM",
"expires_in": 3600,
"refresh_token": "MSwxMDM3MzRU3OUMktdmTsZpCDveWT5XMxQOG1SQTtNzczLVUcHOzNADEsbwGFV",
"token_type": "bearer"
}
Potential errors and responses are the same as the code exchange request and are described above.
A new refresh token may be issued during the process to obtain a new access token. Your application should discard the previous refresh token and store the new value. Ensure your application stores the new value securely.
While 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.