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
- IP address based authentication for institutional subscribers of Scopus/ScienceDirect:
- This is the default for any newly registered APIKey. Clients authenticating this way get access to all content associated with their institutional account.
- "Token-based" authentication, which includes:
- Using tokens from our Authentication API to resolve IP address conflicts for institutional subscribers of Scopus/ScienceDirect
- Using a proprietary token (an "Institutional Token") created for you by our integration support team
- Using OAuth. We offer an oauth implementation for developers wanting to integrate ScienceDirect and/or Scopus content into client-side applications requiring access to user level (rather than institutional) content
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:
Or use this http header with each request:
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"
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.
- A) Your client application (i.e. your IR system) sends an http GET request to the Authentication API, declaring the product platform you need...
...using the following HTTP request headers:
*Optional. If you don't specify this header, the API responds with JSON-formatted data instead of XML.
||[your API KEY]
- B) The Authentication API checks if your API Key is enabled for access to the Authentication API. If not, it responds with an error.
- C) The API then checks that your IP address maps to a known customer account.
If associated with more than one account, the API provides account 'choice' details:
<choice id="13177831" name="My Account number one"/>
<choice id="13177834" name="My Account number two"/>
D) From here, requesting the appropriate account "choice" delivers a valid authtoken for use in ongoing API transactions from your application:
<authenticate-response choice="[choiceID]" type="ONLINE_REGISTERED">
This authtoken represents a specific customer's entitlements to Scopus.
E) After capturing the authtoken, you can send requests to the Content APIs.
F) The APIs check your API Key for validity, and also check for an expired authtoken.
If the key and authtoken are valid, the APIs apply appropriate account entitlements and respond with a payload. If invalid, the APIs respond with an error.
Note: An authtoken expires two hours after issuance by the Authentication API.
G) The data payload is processed by your client application.
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:
- The insttoken must be kept secure server-side in a password protected environment.
The insttoken represents full access to a customer account within our authentication and entitlements system
- It can't appear in any browser side code
- It can't appear in the address bar
All requests using insttoken must come over https
- It may be revoked at any time, without notice
You submit insttokens in header:
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...
- 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).
- After authentication/approval, ScienceDirect redirects back to your app with an 'Access Token'.
- Pass the 'Access Token' back to us in header 'Authorization' or within parameter 'access_token=' (along with your APIKey) for every request
- Once the Access Token expires, your app needs to send the end user back to us to authenticate again.
For a '3-legged' authentication
- 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).
- After authentication/approval, we redirect back to your app with a unique 'authorization_code' in the response.
- Your app requests an 'Access Token' and "Refresh Token" from the Elsevier OAuth interface using this 'authorization_code' (see step [III] below)
- Your app uses the 'Access Token' to make API requests (i.e. 'implicit grant' above), and remembers the Refresh Token.
- 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'
https://acw.elsevier.com/SSOCore/oauth/authCode?response_type=code&client_id=[yourApiKey]&redirect_uri=[YourAppsRedirectURL]&elsevier_targetAppName=[nameOfYourApp] for '3-legged'
If you want to use oAuth in your application, please contact us