You are here: Home › Documentation › REST API › API Request Authentication

API Request Authentication

This page describes the two authentication methods for the REST API.

All requests submitted to http(s)://api.idilia.com must carry authentication information. This information is used to authorize the request and accumulate usage information.

Authentication credentials can be obtained at https://dev.idilia.com/@@keyreport. This requires that you create a user account if not done yet.

Simple Authentication

The simplest form of authentication is to add the HTTP query parameter key to the request. Its value is the concatenation of your public and private keys displayed against the project. The value transmitted will have 43 characters: 13 for the public key value and 30 for the private key value.

Note: When using this method, requests should use the HTTPS protocol to ensure that the key cannot be intercepted. It is also preferable to use the "POST" method to ensure that Web redirect servers do not include the key in the logs.

Upon receiving a request, the server ensures that the access key is known. If invalid or unknown, response HTTP 401 (unauthorized) is returned.

Signed Requests Authentication

The requests issued can be signed with the private key associated with the profile. Unlike simple authentication, the private key is never transmitted. This provides additional protection against your account being compromised. Requests using this method can safely be sent over HTTP.

The signature is computed using the following process:
  1. Ensure that HTTP header "Host" is added to the request.
  2. Generate the current data time as per RFC 2616 and save as header HTTP "Date". It should be expressed as universal time (UTC/GMT). Example: "Thu, 12 Jan 2012 21:48:59 GMT"
  3. Compute the MD5 hash of the request text:
    • disambiguate: Content of parameter text or of the attached document;
    • paraphrase: Content of parameter text;
    • kb: Content of parameter query.
    Encode the hash in base64. Add as HTTP header "Content-MD5".
  4. Create a string with the concatenation of the date, host, request URI, and content MD5. Adding a hyphen between each. This should result in a string such as: "Thu, 12 Jan 2012 21:48:59 GMT-api.idilia.com-/1/text/disambiguate.mpxml-CY9rzUYh03PK3k6DJie09g=="
  5. Create an HMAC-SHA256 signature of this string using your private key.
  6. Encode the signature in base64.
  7. Add HTTP header "Authorization" to the request with the content "IDILIA access_key:signature". Example: "Authorization: IDILIA IdiD7Vf3Gs5G0:ScDel9yyZgwC9Dd2BOO5WYtXYtVApMM60b1sfGs9aJg="

Upon receiving a request, the server ensures that all HTTP required headers are present, the access key is known, the date was generated within the last 15 minutes, the content received matches the transmitted MD5, and the signature matches the expected value. If any of these are not satisfied, response HTTP 401 (unauthorized) is returned with an appropriate error message.