category: Application fundamentals

The Stormancer APIs are secured through a client generated API token. The token should be included in all requests.

Including a token in a request

Stormancer looks for a token in HTTP requests in the following order:

  • x-token request header
  • x-token query parameter
  • x-token cookie value

Most of the time, you will include the token as an x-token request header. Using a query parameter is useful when tinkering or when using a Library that doesn't support adding headers to the request. Finally, setting a cookie enable a browser to perform a request in HTML (for instance to download css, js or other content deployed with a custom admin page

Creating a token

The API caller is responsible for creating these token using the application key provided by the Stormancer portal. Tokens also embed an expiration date. Once created, a token remains valid until the expiration date is reached. When crafting tokens, we advise you to:

  • Use a short token duration, to limit the effect of a potential token thief and reuse. If it's theoretically possible to create long duration tokens, theft of such a token would force you to regenerate your application key to prevent malicious use. We recommend token duration of a few minutes, to accommodate clock offset issues between the Stormancer platform and your server.
  • Create a new token for each API call.

Our management libraries follow these recommandations

Token Structure

The token is a string consisting in two parts, separated by a dot. The first part contains the data: currently expiration date, serialized into a JSON UTF8 string, with a base64 encoding. The second part is a SHA256 signature of the first part.

{data}.{signature}

For instance:

eyJFeHBpcmF0aW9uIjoiMjAxMy0wNi0wN1QxNjowNzoxMy41ODEzOTA5WiIsIklzc3VlZCI6IjIwMTMtMDYtMDdUMTY6MDc6MDguNTgxMzkwOVoifQ==.ZUyBBcyFovKVbOGlnWsy1vx8+V0Y6FaQNbAava7PehM=

Data

The token data is a JSON object, with an Expiration field containing the expiration date of the token (UTC), encoded using the [ISO8601] date format.

{"Expiration":"2013-04-07T15:51:08.2515336Z"}

The json data string should be encoded into a base64 string, using UTF8.

Signature

The signature is generated using a simple algorithm: Concat the data string with the secret key of your application Compute the SHA256 hash using UTF8 encoding. base64 encode the hash.

Secret keys

Local dev platform

For the local dev platform, the secret key is always "key1".

Live environment

For the Stormancer live environment, each application can use 2 secret keys. You can use either one when calling the API.

These 2 keys enable you to regenerate your keys without interruption of service. To do that: Your application uses KEY1. Regenerate KEY2. Switch to KEY2 in your application. Regenerate KEY1.

Using the token

When calling an API, set the x-token header to your generated token.

curl --header "x-token: {token}" http://api.stormancer.com/{api}

Code samples

.NET

Stormancer provides an easy to use client management library for .NET 4.

To manually create a token, first create the token data, using for instance the awesome Json.net library

var data = Base64Encode(JsonConvert.SerializeObject(new {Expiration = DateTime.UtcNow.AddMinutes(1)});

Where the Base64Encode method is defined as:

string Base64Encode(string data)
{
   try
   {
       var byte_data = System.Text.Encoding.UTF8.GetBytes(data);
       string encodedData = Convert.ToBase64String(byte_data);
       return encodedData;
   }
   catch (Exception e)
   {
       throw new Exception("An error occured during base 64 encoding.", e);
   }
}

Then, create the token:

var token = string.Format("{0}.{1}", str, ComputeSignature(str, key));

The ComputeSignature method uses SHA256CryptoServiceProvider to create the signature:

string ComputeSignature(string data, string key)
{
    using (var sha = SHA256CryptoServiceProvider.Create())
    {
        sha.Initialize();
        var bytes = System.Text.Encoding.UTF8.GetBytes(data + key);
        return Convert.ToBase64String(sha.ComputeHash(bytes));
    }
}

Order: 10