Specifying headers

All requests to Content Manager OnDemand REST Services must include at least two HTTP headers: an authorization header and a date header.

Authorization header

All requests to Content Manager OnDemand REST Services must be authorized. Authorizing a request is accomplished by using a standard HTTP Authorization header. This header consists of the authorization scheme, access key, and if signing requests, a signature.

Any attempt to access a service requiring authorization, without the appropriate header, will be denied with a return code of 401 Unauthorized.

Authorization header format

Authorization: Scheme AccessKey:Signature

Scheme

The authorization header scheme can be either CMODSharedKey or CMODSharedKeyV2. The difference in the two schemes is that the CMODSharedKeyV2 scheme does not require the application server URL, such as https://<hostname:port>, in the signature. See the information under the Signature heading for details on signature string construction.

In environments where multiple REST Services instances are deployed and the requests are distributed by a load balancer, the CMODSharedKeyV2 scheme is recommended. The application server URL is required for the CMODSharedKey scheme. This would likely be incorrect and cause signature verification to fail.

Access Key

The access key is created by the ODRESTAdmin generateKeys configuration step. See Creating Keys for more details. The access key contains the connection pool name, a dash, and a secret (symmetric) key, in the form of <pool name>-<secret key>. Because an access key is tied to a connection pool, which in turn is tied to a Content Manager OnDemand user, a given request will only return data to which the Content Manager OnDemand user has permissions.

Example Access Key

externpool1-P0mFoCU5H83lN9uQcRUA

Signature

The signature portion of the Authorization header is constructed from elements of a given request. Each authorization scheme (CMODSharedKey and CMODSharedKeyV2) has its own signature requirements. These requirements are shown for each scheme in the following examples. The elements are shown in order with an example value in brackets [ ]. As shown in the pseudocode examples, only the value is required, and it must be followed by a new line character.

Once the signature elements are constructed as a single string, this string should be signed with the Secret key that was generated by using the ODRESTAdmin generateKey command that is described in Creating keys. This string should then be Base64 encoded.

CMODSharedKey

HTTP-Verb [Get|Post|Put|Delete]
        usi-date or Date [2020-02-03T23:31:04Z]
        Server URL [https://<hostname:port>]
        Resource URI [/cmod-rest/v1/ping]
        AccessID [externpool1-P0mFoCU5H83lN9uQcRUA]

CMODSharedKeyV2

HTTP-Verb [Get|Post|Put|Delete]
        usi-date or Date [2020-02-03T23:31:04Z]
        Resource URI [/cmod-rest/v1/ping]
        AccessID [externpool1-P0mFoCU5H83lN9uQcRUA]

The resource URI should not include query parameters.

The following is pseudocode that shows the construction of each of the two types of Authorization request headers:

CMODSharedKey signature

StringToSign = Verb + "\n" + Date + "\n" + URL + "\n" + Resource + "\n" + AccessKey;
Signature = Base64( (Hmac-SHA256 ( SecretKey, UTF-8-Encoded (StringToSign) );
String Authorization = "CMODSharedKey" + " " + AccessKey + ":" + Signature;

CMODSharedKeyV2 signature

StringToSign = Verb + "\n" + Date + "\n" + Resource + "\n" + AccessKey;
Signature = Base64( (Hmac-SHA256 ( SecretKey, UTF-8-Encoded (StringToSign) );
String Authorization = "CMODSharedKeyV2" + " " + AccessKey + ":" + Signature;

The following example shows the data (verb, date, resource, and access key) that would be used to sign a GET request to retrieve a Content Manager OnDemand document using the CMODSharedKeyV2 authorization header. The ODWEK document ID is shortened for clarity.

Signature data

GET
        2020-02-03T23:31:04Z
        /cmod-rest/v1/hits/Ledger Reports/Y2BN9Y/iiqZRQKNZZ7xgk5t4+...
        externpool1-P0mFoCU5H83lN9uQcRUA

Do not encode any portion of the data being signed. When validating the signature, the REST services will have already decoded the incoming data. Encoding and then signing will cause the signature calculation to fail resulting in a 401 UNAUTHORIZED response code.

Fully constructed Authorization header

The following example shows a fully constructed Authorization header using the CMODSharedKeyV2 scheme and a signed request:

Authorization header

Authorization: CMODSharedKeyV2 externpool1-P0mFoCU5H83lN9uQcRUA:UYLvg6pjA58OXVglgN50xajG+IHog/AKhBIY=

Date header

All requests must include the Coordinated Universal Time (UTC) timestamp in the request. You can do this by either specifying the usi-date header or by using the standard HTTP/HTTPS Date header. If both headers are included, the value of the usi-date is used as the requests creation time. The date header is also used in the signing of authorized requests.

Date header

usi-date: 2023-11-13T18:32:22Z