Overview

You can use the API tokenization feature 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:

• Route("users/{id}/keys"), HttpGet]
• [Route("users/{id}/keys/{key}"), HttpDelete]
• [Route("users/{id}/keys"), HttpPost]
• [Route("users/{id:int}/ActivationCode"), HttpGet]
• [Route("users/resetpassword"), HttpPost]
• [Route("users/setpassword"), HttpPost] - 
• [HttpPut, Route("users/{id:int}")]
• [Route("users/status"), HttpPost]
• [Route("users/"), HttpPost]
• [Route("users/{userId:int}/invite"), HttpPost]
• [Route("users/LockedOut/{accountId}/{email}"), HttpGet]
• [Route("users/unlock/{accountId}/{email}"), HttpPost]
• [Route("users/softDelete"), HttpDelete]
• [Route("usersecurity/challengephrase"), HttpPut]
• [Route("usersecurity/securityinformation/{referencekey}"), HttpGet]
• [Route("usersecurity/securityinformation/{referencekey}"), HttpPost]
• [Route("usersecurity/securityinformation/existing/{referencekey}"), HttpPost]
• [Route("usersecurity/challengephrase/{userId}"), HttpGet]
• [Route("usersecurity/validatemfaphone"), HttpPost]
• [Route("usersecurity/securityinformation/{accountId}/{userId}"), HttpPost]
• [Route("usersecurity/validatephoneapppin"), HttpPost]

Step 1: Create an API Key

When you create an API Key, you will generate a Secret Key. This key will never expire; however, you must securely store this key. Armor cannot retrieve this key for you. 

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.

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}

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: http://local.api.firehost.net/roles
2. Click Headers. 
3. Under Key, select Authorization. 
4. In Value, enter {{hmacAuthHeader}}.
5. Click Pre-request Script. 
6. 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: 

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 Armor API Guide.

Troubleshooting API tokenization

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

• You may not have permissions to use this feature.
  • You must have the following permissions enabled: 
    • API Keys All Read 
    • API Keys All Delete 
    • API Keys Self Manage 
  • To learn how to update your permissions, see Roles and Permissions (Armor Complete) or Roles and permissions (Armor Anywhere).