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 API operation name followed by a new line
5. Append the HTTP content-type, if any, followed by a new line
6. Append the SHA1 hash of the request body, if any, followed by a new line
7. Append the timestamp of the request in RFC 1123 format
8. Create the signature using the HMAC 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" +
    Operation + "\n" +
    Content-Type + "\n" +
    Content-SHA1 + "\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:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Header>
        <Authorization xmlns="http://schemas.requirementslive.com/api"> MzVFMkIyNzhFOUE4ODUwNjEzMUY0MTk3RUQzQTRCRTg=</Authorization>
        <Timestamp xmlns="http://schemas.requirementslive.com/api"> Fri, 13 Sep 2013 13:13:13 +0000</Timestamp>
    </s:Header>
    <s:Body>
        <ListApps></ListApps>
    </s:Body>
</s:Envelope>

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
UserName	The name of the user with the corresponding public key

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

1. Create a base-64 encoded SHA1 hash of the date and time in RFC 1123 format. This is the timestamp hash.
2. Create a base-64 encoded SHA1 hash of the request body. This is the request hash.
3. Create a SignedInfo element with SignatureMethod (SHA1 or SHA256), CanonicalizationMethod and add references to the timestamp and request hashes.
4. Canonicalize the SignedInfo element xml and then calculate the SignatureValue of the SignedInfo based on algorithms specified in SignedInfo. This is the signature hash.
5. Construct the Signature element by including the SignedInfo and Signature, Object(s) (if desired, encoding may be different than that used for signing), KeyInfo (if required), and SignatureValue.
6. For more information on XML signatures, click here.

Example pseudo-code:

					
Signature = "<Signature>..." + SignedInfo "..." + "SignatureValue" +"...</Signature>";

SignatureValue = "<SignatureValue>..." + Base64(HMAC-SHA1(PrivateKey, C14N(SignedInfo)) + "...</SignatureValue>";

SignedInfo = "<SignedInfo>..." + RequestHash + "..." + TimestampHash + "...</SignedInfo>";

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

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

For example:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Header>
        <Timestamp xmlns="http://schemas.requirementslive.com/api">{{Timestamp}}</Timestamp>
        <UserName xmlns="http://schemas.requirementslive.com/api">{{UserName}}</UserName>
        <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
            <SignedInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
                <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
                <SignatureMethod Algorithm="{{SignatureMethod}}" />
                <Reference URI="">
                    <Transforms>
                        <Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
                        <XPath xmlns:rql="http://schemas.requirementslive.com/api">ancestor-or-self::rql:GetAppMap</XPath>
                        </Transform>
                    </Transforms>
                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                    <DigestValue>{{RequestHash}}</DigestValue>
                </Reference>
                <Reference URI="">
                    <Transforms>
                        <Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
                        <XPath xmlns:rql="http://schemas.requirementslive.com/api">ancestor-or-self::rql:Timestamp</XPath>
                        </Transform>
                    </Transforms>
                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                    <DigestValue>{{TimestampHash}}</DigestValue>
                </Reference>
            </SignedInfo>
            <SignatureValue xmlns="http://www.w3.org/2000/09/xmldsig#">{{Signature}}</SignatureValue>
        </Signature>
    </s:Header>
    <s:Body>
        {{Request}}
    </s:Body>
</s:Envelope>

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

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