Elsevier Developer Portal

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

• 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, as documented here.

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.



The steps:

• A) Your client application (i.e. your IR system) sends an http GET request to the Authentication API, declaring the product platform you need...

http://api.elsevier.com/authenticate?platform=SCOPUS

...using the following HTTP request headers:



Action	Header Name	Header Body
Add	X-ELS-APIKey	[your API KEY]
Modify*	Accept	text/xml, application/atom+xml

*Optional. If you don't specify this header, the API responds with JSON-formatted data instead of XML.


• 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:



    Request: http://api.elsevier.com/authenticate?platform=SCOPUS

    <authenticate-response>
    <pathChoices>
    <choice id="13177831" name="My Account number one"/>
    <choice id="13177834" name="My Account number two"/>
    </pathChoices>
    </authenticate-response>
	

• D) From here, requesting the appropriate account "choice" delivers a valid authtoken for use in ongoing API transactions from your application:



    Request: http://api.elsevier.com/authenticate?platform=SCOPUS&choice=[choiceID]

    <authenticate-response choice="[choiceID]" type="ONLINE_REGISTERED">
    <authtoken>
    <sat_9D3208CAAA3D6643A8C82997C50DA74976D7384009A2C6F4D5D780E3A2CAE02B3103ABD409A165D6DC8A97118B4F9C22D236320B48CBD759600599EDCF60C107AA4B112E1746C79339E74317FDAB63670DA57077C17FAD1C8529A4C1EAEC437630F201CAF93F7F297A1293418E0E6AB38A72706ECC29D4DF387F8C4FB68F0733AB71BCDAD47B8DA3E48D02699E5B59B31FE59D8E66C1106ECEA34484EF76B24AF16EE7257826E025B7D01E957EFEB06FA72469CC0702BAA7>
    </authtoken>
    </authenticate-response>
	

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.

Insttoken Authentication

If automatic IP authentication or use of the Authentication API do not meet your requirements, please contact us through our Elsevier Research Product APIs Support Center.

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.
• It can't appear in any browser side code
• It can't appear in the address bar
2. The insttoken represents full access to a customer account within our authentication and entitlements system
• It may be revoked at any time, without notice
3. All requests using insttoken must come over https

You submit insttokens in header: X-ELS-Insttoken