Global API Settings

You can configure global API settings by browsing to the site configuration of your site and then navigating to the section called "API Settings". From there you'll be able to configure the following settings:

Setting	Description
Enable API Access	You can globally enable or disable a site's API by toggling this setting. This setting overrides the user's "Enable API Access" setting.
Global Public Key Certificate	If you want to use a common public key with multiple API users, you can upload a Global Public Key Certificate to your site. To do this go to your site, and navigate to System > Site Configuration > {{Your Site}} > API Settings. This will also require all API users to digitally sign all API requests. * Public Key Certificate files can be in any common X.509 formats

User API Settings

You can configure per user API settings by browsing to the user. From there you'll be able to configure the following settings:

Setting	Description
Allow API Access	By default, a user can not access the API. You can enable or disable a user's API access by toggling this setting.
API Public Key Certificate	If you want to require this user to digitally sign all API requests, upload a Public Key Certificate. Also, API requests from this user can no longer be signed by a global public key certificate. You can globally assign a site's API certificate by uploading a public key certificate here. A certificate assigned to a user will override this certificate. * Public Key Certificate files can be in any common X.509 formats

When accessing the RQL Platform API using REST, you must provide the proper information so the request can be authenticated. The information is sent using HTTP headers.

Authentication Tickets

To use an authentication ticket after obtaining one from the Authenticate operation, include the following HTTP headers in each request:

Header	Value
Authorization	The authentication ticket received in the response of the Authenticate operation
Timestamp	The date and time of the request in RFC 1123 format

For Example:

GET /rql/api/listapps HTTP/1.1
Host: mysite.mydomain.com
Authorization: MzVFMkIyNzhFOUE4ODUwNjEzMUY0MTk3RUQzQTRCRTg=
Timestamp: Fri, 13 Sep 2013 13:13:13 +0000

Digital Signatures

To use a digital signature, include the following HTTP headers in each request:

Header	Value
Authorization	A concatenation of the user name, a colon, and the digital signature of the request.
Timestamp	The date and time of the request in RFC 1123 format

To construct the digital signature for a REST request, follow these steps:

1. Start with an empty string
2. Append the host name of the site followed by a new line
3. Append the HTTP verb followed by a new line
4. Append the URL Path followed by a new line
5. Append the timestamp of the request in RFC 1123 format
6. Create the signature using the SHA512 and hash algorithm and encode the resulting hash to base-64.

Example pseudo-code:

Authorization = UserName + ":" + Signature;

Signature = Base64(HMAC-Algorithm(PrivateKey, UTF-8-Encoding-Of(StringToSign)));

StringToSign = Site + "\n"
    HTTP-Verb + "\n" +
    URL-Path + "\n" +
    Timestamp + "\n";

For example:

GET /rql/api/listapps HTTP/1.1
Host: mysite.mydomain.com
Authorization: jsmith:bmVx24Q ... many many characters ... KEFTq3LQKNrzJzsN
Timestamp: Fri, 13 Sep 2013 13:13:13 +0000

When accessing the RQL Platform API using SOAP, you must provide the proper information so the request can be authenticated. The information is sent using SOAP message headers.

Authentication Tickets

To use an authentication ticket after obtaining one from the Authenticate operation, include the following SOAP headers in each request:

Header	Value
Authorization	The authentication ticket received in the response of the Authenticate operation
Timestamp	The date and time of the request in RFC 1123 format

For Example:

Digital Signatures

To use a digital signature, include the following SOAP headers in each request:

Header	Value
Signature	A standard XML digital signature block
Timestamp	The date and time of the request in RFC 1123 format

To construct the digital signature for a SOAP request, follow these steps:

1. Create a SHA1 hash of the date and time in RFC 1123 format. This is the timestamp hash.
2. Create a SHA1 hash of the request body. This is the request hash.
3. Create a canonicalized string containing the SignedInfo element with references to the timestamp and request hashes. This is the string to sign.
4. Using a Hash-based message authentication code by hashing the UTF8 encoded version of the string to sign with your private key and convert the result to a base64 encoded string. This is the signature value.
5. Create a signature structure based on the XML digital signature format with the signature value. For more information on XML digital signatures, click here.

Example pseudo-code:

					
Signature = Base64(HMAC-SHA1(PrivateKey, UTF8Encoding(StringToSign));

StringToSign = C14N("<SignedInfo>..." + RequestHash + "..." + TimestampHash + "...</SignedInfo>");

RequestHash = SHA1("<ListApps>...</ListApps>");

TimestampHash = SHA1("Fri, 13 Sep 2013 13:13:13 +0000");
                        

For example:

Below is a table describing tokens used in the above example:

Token	Value
SignatureMethod	The algorithm used when creating the digital signature. This will be http://www.w3.org/2000/09/xmldsig#sha1 for SHA1 and http://www.w3.org/2001/04/xmlenc#sha256 for SHA256.
RequestHash	The SHA1 hash of the request body. The above example will be a hash of "<ListApps></ListApps>".
TimestampHash	The SHA1 hash of the timestamp.
Signature	The SHA1 signature or SHA256 signature of the <SignedInfo> element and its contents using a private key.
UserName	The user name for this request. The signature will be verified using the public key assigned to this user or site.
Timestamp	The date and time of the request in RFC 1123 format.