Applications using EDS API need to consider two different layers of authentication: the application's authentication and the end user's authentication. The end user's authentication and the application's authentication are independent of each another.

Application Authentication

Two methods are available for your application to authenticate to EDS API. EDS API uses either IP based authentication or Username and Password authentication. When using IP Address authentication, users gain access based on the IP Address assigned to the device that they are connecting to. The Username and Password method of authentication uses an authentication token and a session token to gain access to EDS API.

In most cases, the fastest route and best choice for application authentication is IP based authentication. If your application is on a server outside of your institution's IP range, then Username and Password authentication should be used. For example, you should use Username and Password authentication if your application is a mobile app and the IP is the device it is installed on or if you are hosting a multi-tenant application for many different EDS libraries. Each method is described below.

Username and Password Authentication

The Username and Password authentication method generates an authentication token that will identify a customer. This token is good for ALL end users and is used for every call to EDS API. Therefore, it needs to be stored on your server in a place that all users of your application have access to. The authentication token needs to be added to the http header of all subsequent requests. Authentication tokens expire after a specified amount of time. The expiration time is indicated in the response message. A new Username and Password authentication call needs to happen after the token expires. The /authservice/rest/uidauth endpoint provides the authentication token for this authentication method.

Endpoint URL for Username and Password Authentication

POST https://eds-api.ebscohost.com/authservice/rest/uidauth

To Use the /authservice/rest/uidauth Endpoint for Username and Password Authentication (example):

Gather the following information for the request:

Data Parameters

The /authservice/rest/uidauth request must be a POST. There are no mandatory HTTP headers. /authservice/rest/uidauth supports application/xml or application/json.

Request

{
  "UserId":"user","Password":"pass","InterfaceId":"WSapi"
} 

<UIDAuthRequestMessage xmlns="http://www.ebscohost.com/services/public/AuthService/Response/2012/06/01" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <UserId>user</UserId>
  <Password>pass</Password>
  <InterfaceId>WSapi</InterfaceId>
</UIDAuthRequestMessage>

Response

{
  "AuthToken":"64a700ea-9f8c-4331-b5ec-884342fd9b3d",
  "AuthTimeout":"1800"
}

<AuthResponseMessage>
  <AuthToken>bd320b75-18c5-489d-98c6-4bafeb834fbe</AuthToken>
  <AuthTimeout>1800</AuthTimeout>
</AuthResponseMessage>

The response can be XML or JSON. The response format is defined by the Accept value set in the HTTP header. If the Accept value is not present in the HTTP header, the Content-type value in the HTTP header is used. The AuthTimeout value in the response is in seconds.

Please be sure to include the authorization token with every EDS API request. To use this method of authentication, a session token must also be generated using the customer's profile. Subsequent requests must use both the authentication token and the session token to gain access to the API.

IP Address Authentication

When you use IP based authentication, you do not have to call an authentication method using EDS API. If the IP address of your server is registered in EBSCOadmin, the API creates an authentication token for you automatically. Also, you do not have to manage authentication tokens or renew expired tokens when using IP address authentication.

Endpoint URL for IP Address Authentication

POST https://eds-api.ebscohost.com/authservice/rest/ipauth 

To Use the /authservice/rest/ipauth Endpoint for IP Address Authentication (example):

Gather the following information for the request:

Data Parameter

The /authservice/rest/ipauth request must be a POST. There are no mandatory HTTP headers. /authservice/rest/ipauth supports application/xml or application/json.

Request

{
  "Options":["String content"]
}

<IPAuthRequestMessage xmlns="http://www.ebscohost.com/services/public/AuthService/Response/2012/06/01">
  <Options>
    <Option>String content</Option>
    <Option>String content</Option>
  </Options>
</IPAuthRequestMessage>

Response

{
  "AuthToken":"64a700ea-9f8c-4331-b5ec-884342fd9b3d",
  "AuthTimeout":"1800"
}

<AuthResponseMessage xmlns="http://www.ebscohost.com/services/public/AuthService/Response/2012/06/01" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <AuthToken>bd320b75-18c5-489d-98c6-4bafeb834fbe</AuthToken>
  <AuthTimeout>1800</AuthTimeout>
</AuthResponseMessage>

The response can be XML or JSON. The response format is defined by the Accept value set in the HTTP header. If the Accept value is not present in the HTTP header, the Content-type value in the HTTP header is used. The AuthTimeout value in the response is in seconds.

To use this method of authentication, a session token must also be generated using the customer's profile. Subsequent requests must use the session token to gain access to the API.

Application Authentication Points to Remember

• Register all applicable IP(s) in EBSCOadmin.
• You should never have to call /authservice/rest/uidauth if using an in-IP server.
• You should only need to call /authservice/rest/uidauth once every 30 minutes at the most. This is independent of any end user activity.

End User Authentication

Every end user needs to obtain a session token by calling /edsapi/rest/createsession. The /edsapi/rest/createsession method has a critical parameter: guest. Based on the end user's logged-in status, you will send either "y" or "n" for the guest parameter.

You must implement an end user authentication method. For example, if you are running Blacklight, any user that has not logged in through Blacklight's login tools should start off their session with a /edsapi/rest/createsession call. In the /edsapi/rest/createsession call, &guest=y. This will tell EDS API that the end user isn't authenticated and the API should respond with guest level results. If the user does login to Blacklight successfully, you will need to call /edsapi/rest/endsession. Then, you will need to call /edsapi/rest/createsession again with &guest=n. This will change EDS API's responses to include full text, full meta-data, and all the data an authorized end user should see. Similarly, you will need to implement something on your application if you want it to recognize in-IP end users and use that to determine how to call /edsapi/rest/createsession.

End User Authentication Points to Remember

• Use your own authentication system to determine if a user should have full or limited access to EDS results and send the appropriate call to /edsapi/rest/createsession.
• Each end user will have their own session token that will be included on every call to the EDS API.
• Each time a user initiates a session with your application, call the /edsapi/rest/createsession method. It returns a session token. Use guest=y if the end user isn’t authenticated. Use the session token with every /edsapi/rest/search and /edsapi/rest/retrieve call for that user.
• If a user logs out or logs in to your application, don't forget to send an /edsapi/rest/endsession and then a /edsapi/rest/createsession indicating their new login status.

For more information on end user authentication, please refer to the Managing Sessions section.