The CL-INT-API uses HMAC authentication, a keyed-hash message authentication code with two shared keys: AccessKey and SecretKey. After a CL-INT-API partner registers for API access, their LexisNexis® Business Consultant provides the required keys.
The AccessKey and SecretKey are specific to the environment which is referred to as $SERVER in this documentation. The URL for your test and production $SERVER will be provided by the business consultant during implementation.
Authentication Process
During the HMAC authorization, a HmacSHA256 algorithm uses the SecretKey to generate a signature. If the request signature calculated by the system matches the Signature included with the request, the requester will have demonstrated possession of the secret access key, and the request will be processed for the developer to whom the key was issued.
For request authentication, the AccessKey element is the identifier used to compute the signature and, indirectly, the user making the request. The SecretKey is used to calculate the HMAC of a string. The output of the HMAC algorithm is the signature which is sent along with the request in the Authorization header and the AccessKey. The AccessKey is also needed in the headers to ensure proper rate limiting.
The Authorization header is the name of the scheme, followed by a space, followed by colon delimited values of the AccessKey and signature. The CONTENT-MD5 (x-ln-cl-int-api-contentmd5) and DATE (x-ln-cl-int-api-date) are custom headers, which provides clients that may not be able to set data and content-md5 on the request with the libraries they are using to send the info to the server and enable the server to recompute the signature.
As displayed above:
- hmac-256 is the HmacSHA256 algorithm and uses the SecretKey in generating the signature
- CL-INT-API is a constant string and denotes the authorization scheme (custom for CounselLink EDI API) being used.
The parameters for the HMAC algorithm are:
- AccessKey -- Access key provided by the Business Consultant
- VERB -- HTTP verb (e.g., GET) for the resource
- CONTENT-TYPE -- The type of content (e.g., JSON)
- CONTENT-MD5 -- MD5 of payload, even if payload is blank
- DATE -- Current timestamp in ISO 8601 format (IMPORTANT! use UTC)
- RESOURCE_PATH -- Path of the resource (no query parameters)
Request scenario / example
Let's say you need to sign the following request:
POST /matter
Content-Type: application/vnd.cl.int.api.v1.0.0+json
x-ln-cl-int-api-contentmd5: abcde181845a4ca6b8fec737b3512345
x-ln-cl-int-api-date: 2015-07-17T04:00:13Z
If the CL-INT-API user/client has been provided with the following:
- AccessKey = qO5paii108tQ0GdqFT1USw==
- SecretKey = 3EJPojuV3ya31YySNqxhiANOW29LCYyUV6XffglFyPM=
The string that will be signed is:
POST\napplication/vnd.cl.int.api.v1.0.0+json\nabcde181845a4ca6b8fec737b3512345\n2015-07-17T04:00:13Z\n/matter\n
If the resulting signature is "gJi91U9Rq7s+8xe1ZhupxW7Teju9Rxdacu4/6gNguys=" then the Authorization header will be:
Authorization: CL-INT-API qO5paii108tQ0GdqFT1USw==:gJi91U9Rq7s+8xe1ZhupxW7Teju9Rxdacu4/6gNguys
Signing GET Requests
When a GET request is made, the Content-MD5 (content type) and the Content-Type headers are omitted. Therefore, parts of the string that will be signed are left blank.
So if the request is:
With API keys:
- AccessKey - qO5paii108tQ0GdqFT1USw==
- SecretKey - 3EJPojuV3ya31YySNqxhiANOW29LCYyUV6XffglFyPM=
Then the string that will be signed is:
Even though the headers are not listed in the sample GET request, the signed string will have and utilize "\n" as the headers; basically the two headers are treated as blanks.