Authentication

Digest Authentication

ScholarOne Web Services are secured using authenticated web protocols. To successfully access and retrieve data, each operation requires valid authentication credentials to be included in the request. The credentials for your site should already be configured. If you need to verify your username and password, or if you wish to update your credentials, please contact ScholarOne Support by visiting our Support page and selecting the Developer role.

ScholarOne Web Services implement Digest Access Authentication over HTTP(S) to securely exchange credentials. The server generates a unique nonce for each request/response cycle, which is used by the client to create a hashed response including the profile’s API Key. This nonce includes a timestamp and an expiration value to prevent replay attacks. If an expired nonce is received, the server will issue a new nonce, allowing the communication to continue as long as the authentication requirements are met.

All authentication and operations with ScholarOne Web Services are conducted using SSL over HTTPS on TCP port 443 to ensure secure communication.

Server request with no authentication information

GET /api/s1m/v2/submissions/full/contributors/authors/submissionids?ids=%27WEB-2013-0002%27&site_name=web_svcs&external_id=22222 HTTP/1.0
Host: mc-api.manuscriptcentral.com

HTTP/1.0 401 Unauthorized
Server: Apache-Coyote/1.1

Date: Thu, 21 Nov 2013 19:07:30 GMT
WWW-Authenticate: Digest realm="ScholarOneApiService", nonce="8C4XnYR7vPK61DT4VXh9eHm3W86ZSJk8", stale="false"
Content-Type: text/html
Content-Length: 33

Server request with successful authentication

GET /api/s1m/v2/submissions/full/contributors/authors/submissionids?ids=%27WEB-2013-0002%27&site_name=web_svcs&external_id=22222 HTTP/1.0
Host: mc-api.manuscriptcentral.com
Authorization: 	Digest username="sample_user", 
		realm="ScholarOneApiService",
		nonce="8C4XnYR7vPK61DT4VXh9eHm3W86ZSJk8",
	uri="/api/s1m/v2/submissions/full/contributors/authors/submissionids?ids=%27WEB-2013-0002%27&site_name=web_svcs&external_id=22222,
		response="e6c9e7700b33b8d8e534efd9e96d173d"

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Date: Thu, 21 Nov 2013 19:07:55 GMT
Content-Type: application/xml
Content-Length: 1180

(…followed by a blank line and XML or JSON text of the restricted content)

Server response when authentication fails

If the required authentication information is incorrect, the server will send back an HTTP error code in the header. An example of this is illustrated below, where the server response denies access due to the wrong site_name being sent.

HTTP/1.1 500 Internal Server Error
Server: Apache-Coyote/1.1
Date: Thu, 21 Nov 2013 19:07:55 GMT
x-frame-options: DENY
Content-Type: application/xml;charset=UTF-8
Content-Length: 1180

IP Authentication

IP authentication occurs automatically when your IP address is registered within your customer account. Unlike username/password authentication, IP-based authentication does not require authorization information in the request header.

If your client fails to successfully complete ScholarOne's digest authentication, a 401 response code will be returned, and the request will not proceed to the IP validation stage. Both username/password authentication and IP validation are required for successful communication with the ScholarOne Web Services API.

Base64 Encoding References

• Base64 Content encoding scheme

• RFC 2617 HTTP Authentication: Basic and Digest Access Authentication

• Digest access authentication

• Encode and decode using base64 encoding