Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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. 

Note

While any Armor user can reference this document, some content is specifically focused on users who utilize Postman, C#, or Java Script.


...

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. 

Note

If you lose the Secret Key, then you must delete the corresponding API Key in AMP. Afterwards, you must create a new API Key. Armor cannot retrieve your Secret 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.

...

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}

Authentication componentDescription
Authorization TypeARMOR-PSK
Private Key IDUse the Key ID generated in AMP.
HMACSHA512 Signature
Nonce

Enter a unique ID.

  • This ID cannot be longer than 128 characters.
  • This ID cannot contain a colon ( : ). 
TimestampEnter a unix time stamp within 5 minutes of current time.



Note

Sample authentication header: ARMOR-PSK 20a37099-4a0b-432f-bf46-5fa690a0405c:8wliK5PMXBrMNQX0DmXkkpC2YD5j+QtPH2xVRZM7jaaS0hC6jhRmtxy+nKJidDnYTpFc6blsO7+4VfKqslbqzA==:8jbj872s2h:1528140529



  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:


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






Note

Based on your There are three options for you to run the pre-request script: 


...

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: 
ParameterDescription
APP_ID

Enter the Key ID generated from AMP.

Note

In the example below, replace <use the api key id> with your key ID.

SECRET_KEY

Enter the Secret Key generated from AMP.

Note

In the example below, replace <use the secret key> with your secret key.

nonce

Enter a unique ID.

  • This ID cannot be longer than 128 characters.
  • This ID cannot contain a colon ( : ). 
timestampEnter a unix time stamp within 5 minutes of current time.



Code Block
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: 


ParameterDescription
APP_ID

Enter the Key ID generated from AMP.

Note

In the example below, replace <use the api key id> with your key ID.

SECRET_KEY

Enter the Secret Key generated from AMP.

Note

In the example below, replace <use the secret key> with your secret key.


nonce

Enter a unique ID.

  • This ID cannot be longer than 128 characters.
  • This ID cannot contain a colon ( : ). 
timestampEnter a unix time stamp within 5 minutes of current time.




apiKeyEnter the Key ID generated from AMP.
secretKeyEnter the Secret Key generated from AMP.
nonce

Enter a unique ID.

  • This ID cannot be longer than 128 characters.
  • This ID cannot contain a colon ( : ). 
requestPath
requestBody
timestampEnter a unix time stamp within 5 minutes of current time.
httpMethodEnter GET or POST.


Code Block
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:


...