API Authentication

The Elsevier APIs support various authentication methods. For all methods, your application passes in an "APIKey" with each request.

You register for an APIKey here.

Technical Specifications for the apis are here.

API Authentication methods for customers

Each APIKey provides access to a limited amount of content by default. Non-customers wanting content options beyond these defaults need to contact us to discuss their use case.

Automatic IP address based authentication for institutional subscribers of Scopus/ScienceDirect

First, register for an API Key here. You hard-code this API Key into your application.

You either submit the APIKey within a request URL parameter:

http://api.elsevier.com/content/search/scopus?query=heart&apiKey=[apikey] 

Or use this http header with each request:

X-ELS-APIKey: [apikey]

Our systems automatically associate your request with your customer account and return content according to that account's entitlements.
Sometimes we associate multiple IP addresses with different accounts in our account management system. In these situations your code needs to capture and maintain a security device we call an "authtoken"

Authtoken authentication

After obtaining an authtoken from the Authentication API, the client submits the authtoken with each API request.

The following diagram and step-by-step explanation explains this logic in more detail.

Elsevier API Authentication Flow

The steps:


Insttoken Authentication

If automatic IP authentication or use of the Authentication API do not meet your requirements, contact us for more information about obtaining an 'Institutional Token'.

An insttoken is an additional security token submitted in tandem with your APIKey.
Insttokens are only available to customers or partners working on behalf of a customer. If Elsevier grants you an insttoken, there are restrictions to follow:

  1. The insttoken must be kept secure server-side in a password protected environment.
  2. The insttoken represents full access to a customer account within our authentication and entitlements system
  3. All requests using insttoken must come over https

You submit insttokens in header: X-ELS-Insttoken

oAuth Authentication

Developers who want to build ScienceDirect userID and password authentication into their application can use our oAuth API and interface.
We support both 'implicit grant' and '3-legged' authentication via OAuth (more at http://tools.ietf.org/html/rfc5849#section-1.2)

For an 'implicit grant' authentication...

  1. Your app links to our oauth endpoint and sends users to it both for entry of their ScienceDirect user credentials and their permission to grant your app access to ScienceDirect (see [I] below).
  2. After authentication/approval, ScienceDirect redirects back to your app with an 'Access Token'.
  3. Pass the 'Access Token' back to us in header 'Authorization' or within parameter 'access_token=' (along with your APIKey) for every request
  4. Once the Access Token expires, your app needs to send the end user back to us to authenticate again.
For a '3-legged' authentication
  1. Your app links to our oauth endpoint, and sends users to it for entry of their ScienceDirect user credentials and their permission to grant your app access to ScienceDirect (see step [II] below).
  2. After authentication/approval, we redirect back to your app with a unique 'authorization_code' in the response.
  3. Your app requests an 'Access Token' and "Refresh Token" from the Elsevier OAuth interface using this 'authorization_code' (see step [III] below)
  4. Your app uses the 'Access Token' to make API requests (i.e. 'implicit grant' above), and remembers the Refresh Token.
  5. Once the Access Token expires, API requests stop working. Your app requests new Access and Refresh Tokens using the previous Refresh Token. (see step [IV] below). Your app can repeat this step indefinitely, without the need for explicit user re-authentication.
[I] https://acw.elsevier.com/SSOCore/oauth/authCode?response_type=token&client_id=[yourApiKey]&redirect_uri=[YourAppsRedirectURL]&elsevier_targetAppName=[nameOfYourApp] for 'implicit'

[II]
https://acw.elsevier.com/SSOCore/oauth/authCode?response_type=code&client_id=[yourApiKey]&redirect_uri=[YourAppsRedirectURL]&elsevier_targetAppName=[nameOfYourApp] for '3-legged'

[III]
https://acw.elsevier.com/SSOCore/oauth/accessToken?grant_type=authorization_code&code=[authorization_code]&redirect_uri=[YourAppsRedirectURL]

[IV]
https://acw.elsevier.com/SSOCore/oauth/accessToken?grant_type=refresh_token&refresh_token=[refreshtoken]
If you want to use oAuth in your application, please contact us.