Elsevier Authentication

generated: '2026-09-06'
method: searched
source: https://dev.elsevier.com/tecdoc_api_authentication.html
docs: https://dev.elsevier.com/tecdoc_api_authentication.html
supporting_sources:
- openapi/elsevier-scopus-swagger.json (and the six sibling Swagger 2.0 documents harvested from dev.elsevier.com/elsdoc/)
- wadl/ (37 first-party WADL contracts; header parameters counted across 138 methods)
- https://dev.elsevier.com/support.html
- live probe of https://api.elsevier.com/content/search/scopus, unauthenticated, 2026-09-06
description: >-
  Elsevier layers four things that all get called "authentication": an API key that identifies
  the APPLICATION, and then three different ways of establishing WHICH CUSTOMER ACCOUNT the
  call is entitled to read as. The key alone gets you almost nothing — entitlement is resolved
  from institutional IP address, an authtoken, or an insttoken. An agent running outside an
  institutional network will authenticate successfully and still be refused content, and that
  is the single most misread thing about this API.
summary:
  types:
  - apiKey
  - bearer-like-token
  - oauth2
  api_key_in:
  - header
  - query
  entitlement_model: institutional
  scopes_published: false
schemes:
- name: apiKey
  type: apiKey
  in: header
  parameter: X-ELS-APIKey
  required: true
  description: >-
    Required on every request to every API. Registered self-serve at
    https://dev.elsevier.com/apikey/manage.
  observed_in_wadl_methods: 122
- name: apiKeyQuery
  type: apiKey
  in: query
  parameter: apiKey
  required: false
  description: >-
    Elsevier documents the key as a URL query parameter as an explicit alternative to the
    header, and its own portal examples embed it that way in <object>/<iframe> tags.
  observed_in_wadl_methods: 123
  risk: >-
    Credentials in the query string are logged by intermediaries and land in browser history
    and referrers. This is the one place the Elsevier contract fails the
    credentials-not-in-query test, and it fails it because the provider recommends it.
- name: authtoken
  type: apiKey
  in: header
  parameter: X-ELS-Authtoken
  required: false
  description: >-
    Obtained from the Authentication API (GET https://api.elsevier.com/authenticate?platform=SCOPUS),
    which resolves the caller to one customer account when the source IP maps to more than one.
    The response either returns an authtoken or a <pathChoices> list to pick from with &choice=.
  ttl: 2h
  ttl_source: >-
    "An authtoken expires two hours after issuance by the Authentication API." —
    dev.elsevier.com/tecdoc_api_authentication.html
  observed_in_wadl_methods: 110
- name: insttoken
  type: apiKey
  in: header
  parameter: X-ELS-Insttoken
  required: false
  description: >-
    A proprietary Institutional Token issued by Elsevier's integration support team for remote
    access outside the institutional network. Not self-serve — it must be requested.
  restrictions:
  - Must be kept server-side in a password-protected environment.
  - Must never appear in browser-side code or in the address bar.
  - Represents full access to a customer account and may be revoked at any time without notice.
  - All requests using an insttoken must be over HTTPS.
  observed_in_wadl_methods: 106
- name: authorization
  type: http
  scheme: bearer
  parameter: Authorization
  required: false
  description: >-
    An Authorization header is declared on 110 of the 138 WADL methods. Elsevier's auth guide
    describes "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."
  gap: >-
    No authorization endpoint, token endpoint, grant type, client-registration flow or scope
    list is published anywhere on dev.elsevier.com. UPDATED 2026-09-06: the endpoints do
    exist and are discoverable — https://id.elsevier.com serves both an OpenID Connect
    discovery document and RFC 8414 authorization-server metadata anonymously (see
    oauth_discovery below and scopes/elsevier-scopes.yml) — but nothing on the developer
    portal or the API host names that server, and none of its 35 advertised scopes governs a
    Research Products API operation. The route from a 401 on api.elsevier.com to that token
    endpoint has to be guessed.
- name: crossref-tdm
  type: apiKey
  in: header
  parameter: CR-TDM-Client-Token
  required: false
  description: >-
    Crossref Text and Data Mining client token, accepted on the article/object retrieval
    surface alongside CR-Clickthrough-Client-Token. A cross-publisher standard, not an
    Elsevier-proprietary one.
  observed_in_wadl_methods: 5
oauth_discovery:
  found: true
  method: probed
  probed: '2026-09-06'
  issuer: https://id.elsevier.com
  software: PingFederate
  how_found: >-
    https://dev.elsevier.com/apikey/manage returns 302 to
    https://id.elsevier.com/as/authorization.oauth2 with client_id ELSAPI-PROD and a scope
    list including urn:idp:policy:product:confirmation:EAPI:emailconfirmation. EAPI is the
    developer portal. The host was then probed directly.
  documents:
  - url: https://id.elsevier.com/.well-known/openid-configuration
    status: 200
    file: ../well-known/elsevier-id-openid-configuration.json
  - url: https://id.elsevier.com/.well-known/oauth-authorization-server
    status: 200
    file: ../well-known/elsevier-id-oauth-authorization-server.json
  - url: https://api.elsevier.com/.well-known/oauth-protected-resource
    status: 404
  endpoints:
    authorization: https://id.elsevier.com/as/authorization.oauth2
    token: https://id.elsevier.com/as/token.oauth2
    introspection: https://id.elsevier.com/as/introspect.oauth2
    revocation: https://id.elsevier.com/as/revoke_token.oauth2
    userinfo: https://id.elsevier.com/idp/userinfo.openid
    registration: https://id.elsevier.com/as/clients.oauth2
    device_authorization: https://id.elsevier.com/as/device_authz.oauth2
    jwks: https://id.elsevier.com/pf/JWKS
  pkce: [plain, S256]
  scopes: see scopes/elsevier-scopes.yml
  scope_count: 35
  applies_to: >-
    Elsevier account identity across its web products (ScienceDirect, SciVal, Pure, Mendeley,
    and the developer portal sign-in). NOT the Research Products APIs on api.elsevier.com,
    which remain key-plus-entitlement. Do not read this discovery document as an authorization
    model for the content APIs.
  weaknesses:
  - implicit and password grants still advertised
  - id_token_signing_alg_values_supported includes "none"
  - no oauth-protected-resource document on the API host to link the two
entitlement:
  primary: institutional-ip
  description: >-
    "Elsevier Research Products APIs rely primarily on Institutional IP address for
    authentication. API access through proxies is not supported." Content returned is scoped
    to the subscriptions of whichever account the IP resolves to.
  failure_mode: >-
    A valid key called from outside the institutional network returns 401/403 with
    X-ELS-Status AUTHENTICATION_ERROR or an entitlement error — indistinguishable at the status
    code from a bad key. The X-ELS-Status header is the only thing that separates them.
  remote_access: Institutional Token (X-ELS-Insttoken), by request only.
error_signals:
  header: X-ELS-Status
  observed:
  - value: AUTHENTICATION_ERROR - Invalid API Key
    status: 401
    probed: 'https://api.elsevier.com/content/search/scopus?query=heart (no key), 2026-09-06'
  envelope: '{"service-error":{"status":{"statusCode":"...","statusText":"..."}}}'