Entitlement API Specification – Integrators

Version: 2.1 (July 2021)  Entitlement API – Integrator – vs 2.1

Audience: Integrators, consumers of the GetFTR Entitlement API

Contributors: GetFTR Technical Steering Group (TSG)

Document revision history

The Entitlement API establishes for a given document (DOI) and user affiliated institution the entitled level of access and appropriate content links, whether that be to the Version of Record or Alternative Version.

For brevity throughout the specification the following acronyms will be used:

Provides capability to establish entitlements for a single Organisation and a list of Documents (DOIs). The Organisation can be identified by a number of ID schemes.

Request

POST /v2/entitlements

{
  "org": {
    "ipv4": "...",
    "entityID": "...",
    "ringgoldID": "...",
  },
  "dois": [
    "...",
    "..."
  ]
}

Response

For every document a corresponding Entitlement resource is returned, which establishes the level of entitlement; access type; document type (version of record or alternate); content type and ultimately a link to the actual resource if appropriate.

{
    "entitlements": [
        {
            "doi": "...",
            "statusCode": 200,
            "entitled": "yes",
            "accessType": "...",
            "org": {
                "ipv4": "..."
            },
            "vor": [
                {
                    "contentType": "...",
                    "url": "..."
                }
            ],
            "document": "..."
        }
    ]
}

Entitlements is a list of Entitlement resources, where the order of DOIs are preserved from the request.

For a complete set of scenarios refer to Entitlement API – Integrator – vs 2.1

Entitlement object

Document object

Entitlement truth table

The following truth table captures the legal combinations of VoR and AV in the Entitlement resource:

Transport (TLS)

All communications are encrypted over a TLS 1.2, or above, connection. The TLS handshake will exchange server certificates only.

Integrator ID

getFTR issues each Integrator with a unique “Integrator ID” String. Integrators present this identifier in every request as the HTTP header “X-INTEGRATOR-ID”. getFTR will use this to lookup the “shared secret” (below).

Authentication (JWT)

Integrators must sign all API requests with a JWT bearer token (rfc7519), which getFTR is responsible for verifying.

getFTR issues each Integrator with a unique shared secret, a pseudo random generated 256 bit long number encoded in Base64. This must be decoded into a raw byte array when signing and verifying requests.

The following JWT properties, exhaustive list, have been adopted:

doi is the only business property extension to the JWT payload, deemed enough to confirm the authenticity of the Integrator and integrity of the request.

Integrators are responsible for generating valid Bearer tokens. Refer to Status Codes.

Example

Shared Secret

JWT Token Header

{  
  "alg": "HS256",
  "typ": "JWT"
}

JWT Token Payload

{  
  "iss": "mendeley",
  "aud": "getftr",
  "iat": 1568110518,
  "jti": "aa2d6150-c89a-46af-9dd1-8ed04be80b0f",
  "doi": "12.345/2018zz112233"
}

JWT Auth Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtZW5kZWxleSIsImF1ZCI6ImdldGZ0ciIsImlhdCI6MTU2ODExMDUxOCwianRpIjoiYWEyZDYxNTAtYzg5YS00NmFmLTlkZDEtOGVkMDRiZTgwYjBmIiwiZG9pIjoiMTIuMzQ1LzIwMTh6ejExMjIzMyJ9.7j1C0-3pzXDRX3MlLCrV38EVA1P-pb7YOMPLm4VIBaw

Resources

• https://jwt.io/#debugger-io
• https://mkjwk.org/
• https://www.unixtimeconverter.io/

Quality of Service (QoS)

Each request must include a X-API-KEY HTTP header, supplied by getFTR . This is to ensure all Integrators get the same Quality of Service, and no one Integrator overloads getFTR. Integrators should gracefully handle a 429 Response Code (Too Many Requests)

Each request must include a unique X-REQUEST-ID HTTP header which will be carried forward:

X-REQUEST-ID: 3e5980ba-ceae-4976-a9d4-c7e6ac49a20b (GUID)

Major Versions

Major version changes result in a breaking change to the interface contract. The major version number (X below) is declared in the path as follows:

/vX/entitlement?doi={doi}

This specification is at version 1.0 and is reflected in the path as follows:

/v1/entitlement?doi={doi}

Minor Versions

Minor version changes result in a non-breaking change (e.g. additional SAML attribute support). The minor version is not reflected in the path.

Robustness

getFTR will conform completely to the specification, but Integrators must be able to accept input with any non-breaking changes. In other words:

“Be liberal in what you accept, be conservative in what you send”
(Postel’s Law, aka The Robustness Principle )

Batch Level (HTTP)

The following status codes are returned via the standard HTTP Status Code Header:

Item Level (JSON)

The following status codes are returned via the JSON response body:

Encoding & Formatting

The following rules apply to Entitlement API request and response structures:

Single line JSON

The JSON body response must be single line, with no line feeds or carriage returns. 

Whitespace

No white space between properties and values in the JSON response. 

Character Encoding

UTF-8 is the adopted character encoding standard.

The Entitlement API specification adopts a number of open standards and patterns, outlined below:

HTTP Headers

All adopted HTTP headers are listed here: