Overview

You can use the API tokenization feature (Postman and Javascript) in the Armor Management Portal (AMP) to create an API key. This key will help you log into the Armor API system. 

After you create a key, you can use a GET request to log into the Armor API system. 

...

.

...

Before you begin

If you access the Armor API system through an AMP-generated API Key, then you will not be able to access the following endpoints:

...

...

Step 1: Create

...

an API

...

key

...

1. In the Armor Management Portal (AMP), in the left-side navigation, click Account. 
2. Click Users. 
3. Click API Keys. 
4. Click the plus icon. 
5. Enter a descriptive name, and then click Create Key. 
6. Copy the Key ID and Secret Key. 
7. Click Close. 
8. The API Keys table will display a new entry.

Insert excerpt
Pre-Shared Key Authentication Method Pre-Shared Key Authentication Method name Create API Key nopanel true

Step 2: Authenticate into the Armor API system

To authenticate into the Armor API system, enter the following type of request header value: {Authorization Type} {Private Key ID}:{HMACSHA512 Signature}:{Nonce}:{Timestamp}

...

Enter a unique ID.

• This ID cannot be longer than 128 characters.
• This ID cannot contain a colon ( : ). 

...

1. MOR-PSK 20a37099-4a0b-432f-bf46-5fa690a0405c:8wliK5PMXBrMNQX0DmXkkpC2YD5j+QtPH2xVRZM7jaaS0hC6jhRmtxy+nKJidDnYTpFc6blsO7+4VfKqslbqzA==:8jbj872s2h:1528140529

1. Nonce max length is 128 characters. Nonce can't contain a colon : as it is being a delimeter
2. Authorization is composed of 'ARMOR-PSK' then a space and AppId:Signature:Nonce:timeStamp (4 values are separated by : )
   1. AppId: Generated from UI by the user
   2. Singature: All of the following values concatenated without any spaces. Then Use Sha512 to create hash
      1. AppId
      2. HttpMethod: Get/Post/Delete...
      3. requestPath:
      4. Nonce:
      5. timestamp
      6. requestbody: for get empty string. For others, the contents
   3. Nonce: Unique id, can't be reused, up to 128 characters in length
   4. Timestamp: unix time stamp, should be within 5 minutes of current time.
3. ARMOR-PSK 20a37099-4a0b-432f-bf46-5fa690a0405c:8wliK5PMXBrMNQX0DmXkkpC2YD5j+QtPH2xVRZM7jaaS0hC6jhRmtxy+nKJidDnYTpFc6blsO7+4VfKqslbqzA==:8jbj872s2h:1528140529

Authorization Header is composed of the following

Request Header Key: authorization

Request Header Value: {Authorization Type} {Private Key ID}:{HMACSHA512 Signature}:{Nonce}:{Timestamp}

Example:

authorization:"ARMOR-PSK 4040bbda-4d23-4a3f-a378-27bb11666d1c:ibLFa2KRljkvOJKMinGNkxWQCXFBajoM7r9T1nB27Kp3nLfmqm4+zdUOlmK/ZufEamAcVy4DT86UAYiunUC2pQ==:1526656237:1526656237"

Option 1: Postman example

1. In your Postman application, create a new GET request with the following endpoint:

...

1. https://

...

1. api.

...

1. armor.

...

1. com/roles

...

1. Click Headers.

...

...

1. Under Key,

...

1. select Authorization.

...

...

1. In Value,

...

1. enter {{hmacAuthHeader}}

...

1. .

2. Under Key, select Content-Type.

3. In Value, enter application/json.

4. Click Pre-request Script.

...

2. Enter the script below with the following updated parameters:

...

function getPath(url) {
    var pathRegex = /.+?\:\/\/.+?(\/.+?)(?:#|\?|$)/;
    var result = url.match(pathRegex);
    return result && result.length > 1 ? result[1] : '';
}
  
function getQueryString(url) {
    var arrSplit = url.split('?');
    return arrSplit.length > 1 ? url.substring(url.indexOf('?')+1) : '';
}
  
function getAuthHeader(httpMethod, requestUrl, requestBody) {
    *var APP_ID = '<use the api key id>';*
    *var SECRET_KEY = '<use the secret key>';*
    var AUTH_TYPE = 'ARMOR-PSK';
    var requestPath = getPath(requestUrl).replace('https', 'http');
    var queryString = getQueryString(requestUrl);
    if (httpMethod == 'GET' || !requestBody) {
        requestBody = '';
    } else {
        requestBody = requestBody.toString();
        requestBody = CryptoJS.enc.Base64.stringify(CryptoJS.SHA512(requestBody));
    }  
    var timestamp = Math.round(new Date().getTime() / 1000);
    var nonce = timestamp;
    var requestData = [APP_ID, httpMethod, requestPath, nonce, timestamp, requestBody].join("");
    var mac = CryptoJS.HmacSHA512(requestData, SECRET_KEY);
    var signature = CryptoJS.enc.Base64.stringify(mac);
    var authHeader = AUTH_TYPE + ' ' + APP_ID + ':' + signature + ':' + nonce + ':' + timestamp;
    return authHeader;
}
postman.setEnvironmentVariable('hmacAuthHeader', getAuthHeader(request['method'], request['url'], request['data']));

Option 2: C# example

1. Enter the script below with the following updated parameters: 

...

...

Enter the Secret Key generated from AMP.

...

Enter a unique ID.

• This ID cannot be longer than 128 characters.
• This ID cannot contain a colon ( : ). 

...

Enter a unique ID.

• This ID cannot be longer than 128 characters.
• This ID cannot contain a colon ( : ). 

...

namespace FireHost.Infrastructure.RBAC.UnitTests
{
    using System;
    using System.Security.Cryptography;
    using System.Text;
 
    public static class AuthHeaderHelper
    {
        /// <summary>
        /// The following function creats the needed authentication header to work for ApiToken
        /// HttpRequestMessage.Headers.Authorization = new AuthenticationHeaderValue("ARMOR-PSK", authValue)
        /// </summary>
        /// <param name="apiKey">Unique Id created by the customer</param>
        /// <param name="secretKey">The secret key generated by the customer.</param>
        /// <param name="nonce">A unique value, has 5 min lifespan</param>
        /// <param name="requestPath">absolute path: Example: /accounts/2</param>
        /// <param name="requestBody">Request body applies.</param>
        /// <param name="timestamp">Must be current time</param>
        /// <param name="httpMethod">Http Method: GET, POST, ...</param>
        /// <returns>string auth header Example: 'ARMOR-PSK apiKey:signature:nonce:unixTime'</returns>
        public static string CreateAuthorizationHeader(string apiKey, string secretKey, string nonce, string requestPath, string requestBody, DateTime? timestamp, string httpMethod = "GET")
        {
            var dateTime = timestamp ?? DateTime.UtcNow;
 
            using (var sha512 = new SHA512Managed())
            {
                var requestBodyBytes = Encoding.ASCII.GetBytes(requestBody);
                var content = Convert.ToBase64String(sha512.ComputeHash(requestBodyBytes));
                requestBody = content.Length != 0 ? content : string.Empty;
            }
 
            Console.WriteLine("Request Body is: {0}", requestBody);
            requestPath = "/accounts/2".ToLower();
 
            var unixTime = (Int32)(dateTime.Subtract(new DateTime(1970, 1, 1))).TotalSeconds;
            var requestData = string.Format("{0}{1}{2}{3}{4}{5}", apiKey, httpMethod, requestPath, unixTime, nonce, requestBody);
            Console.WriteLine("Request Data is: {0}", requestData);
            string signature = string.Empty;
            using (var hmac = new HMACSHA512(Encoding.UTF8.GetBytes(secretKey)))
            {
                var result = hmac.ComputeHash(Encoding.UTF8.GetBytes(requestData));
                signature = Convert.ToBase64String(result);
            }
 
            return string.Format("{0}:{1}:{2}:{3}", apiKey, signature, nonce, unixTime);
        }
    }
}

Option 3: Javascript

Step 3: Make an API Call

To learn about the different calls that you can make, see see Armor API Guide.

Troubleshooting API tokenization

If you cannot create or access the API Keys screen, consider that:

...

• API Keys All Read 
• API Keys All Delete 
• API Keys Self Manage 

...

Related Documentation

• To learn about the different calls that you can make, see Armor API Guide.

• To learn how to create an API key or to learn a different way to access the Armor API system, see Pre-Shared Key Authentication Method.