Authorization

StartExam API may be used by developer who is the owner or admin of a StartExam App account.
An authenticated request requires two headers: the Date and the Authorization header. The following sections describe how to construct these headers.

Specifying the Date Header

All authenticated requests must include the Coordinated Universal Time (UTC) timestamp for the request. You can specify the timestamp in the standard HTTP/HTTPS Date header using RFC 1123 date format.

Date: Wed, 15 Jan 2014 19:38:50 GMT

API ensures that a request is no older than 15 minutes by the time it reaches the service. This guards against certain security attacks, including replay attacks. When this check fails, the server returns response code 403 (Forbidden).

Specifying the Authorization Header

Every authenticated request must include the Authorization header. The format for the Authorization header is as follows:

Authorization: SharedKey <AccountId>:<Signature>

where

• SharedKey is the common name of the authorization scheme
• AccountId is the private integer identifier of the account requesting the resource
• Signature is a Hash-based Message Authentication Code (HMAC) constructed from the request and computed by using the SHA256 algorithm, and then encoded by using Base64 encoding

To calculate the signature you must follow two steps described below:

1. Construct the String to Sign

To create a StringToSign for a request use the following formula:

StringToSign = VERB + " " + CanonicalPath + " " + Date + " " + Content-Length

where

• VERB is the HTTP verb of the request, such as GET or POST, and must be uppercase
• CanonicalPath is the request absolute path, that does not include the scheme, host name, or query portion of the URI. It starts with / and must be lowercase
• Date is the the request Date header value, the same as described above
• Content-Length is the request Content-Length header value, a long number

The following example shows a well-formed signature string:

POST /v1/participants Sun, 19 Jan 2014 09:55:37 GMT 1045

2. Hash the String to Sign

Take the calculated StringToSign as UTF-8-encoded string, and using the SecretKey provided for your account call the HMAC-SHA256 algorithm and then encode the hash bytes by using Base64 encoding. Use the following logic (shown as pseudocode):

Hash = new HMACSHA256(SecretKey).ComputeHash(UTF8(StringToSign));
Signature = Base64(Hash);

Example

Assume your private account keys are:

• AccountId 500
• SecretKey 18e3213e4e9e42829b253653e624a54a746e987d699c484292e18b53358e23f0

You need to calculate a signature for a following request:

POST https://api.startexam.com/v2/participants HTTP/1.1
Host: api.startexam.com
Accept: application/json; charset=utf-8
Content-Type: application/json; charset=utf-8
Content-Length: 295
Date: Tue, 11 Sep 2018 12:08:34 GMT

{
  "center": "mycenter",
  "validFrom": "2018-09-11T00:00:00Z",
  "validTill": "2020-09-21T23:59:59Z",
  "tests": [
    "13e07e64-5d9b-4b90-bf1f-b1987d57fc59"
  ],
  "employees": [
    {
      "id": "willis74"
    },
    {
      "id": "knightly32"
    },
    {
      "id": "covey77"
    }
  ]
}

You construct the StringToSing from request headers and calculate a Signature using HMAC-SHA256 and your account SecretKey:

• StringToSign POST /v2/participants Tue, 11 Sep 2018 12:08:34 GMT 295
• Signature TXbHhd5eF6CjwcCfuAd/4YAUlszFE7fOnQNmO+K8LV0=

The correct Authorization header would be:

Authorization: SharedKey 500:TXbHhd5eF6CjwcCfuAd/4YAUlszFE7fOnQNmO+K8LV0=

In case Authorization header is incorrect the server returns response code 403 (Forbidden) or 400 (Bad Request) depending on the error subtype.
Read more how to process responses...