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. |
- In the Armor Management Portal (AMP), in the left-side navigation, click Account.
- Click Users.
- Click API Keys.
- Click the plus icon.
- Enter a descriptive name, and then click Create Key.
- Copy the Key ID and Secret Key.
- Click Close.
- 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 component | Description |
---|---|
Authorization Type | ARMOR-PSK |
Private Key ID | Use the Key ID generated in AMP. |
HMACSHA512 Signature | |
Nonce | Enter a unique ID.
|
Timestamp | Enter 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 |
MOR-PSK 20a37099-4a0b-432f-bf46-5fa690a0405c:8wliK5PMXBrMNQX0DmXkkpC2YD5j+QtPH2xVRZM7jaaS0hC6jhRmtxy+nKJidDnYTpFc6blsO7+4VfKqslbqzA==:8jbj872s2h:1528140529
Nonce max length is 128 characters. Nonce can't contain a colon : as it is being a delimeterAuthorization is composed of 'ARMOR-PSK' then a space and AppId:Signature:Nonce:timeStamp (4 values are separated by : )AppId: Generated from UI by the userSingature: All of the following values concatenated without any spaces. Then Use Sha512 to create hashAppIdHttpMethod: Get/Post/Delete...requestPath:Nonce:timestamprequestbody: for get empty string. For others, the contents
Nonce: Unique id, can't be reused, up to 128 characters in lengthTimestamp: unix time stamp, should be within 5 minutes of current time.
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
- In your Postman application, create a new GET request with the following endpoint: http://local.api.firehost.net/roles
- Click Headers.
- Under Key, select Authorization.
- In Value, enter {{hmacAuthHeader}}.
- Click Pre-request Script.
- Enter the script below with the following updated parameters:
Parameter | Description | ||
---|---|---|---|
APP_ID | Enter the Key ID generated from AMP.
| ||
SECRET_KEY | Enter the Secret Key generated from AMP.
| ||
nonce | Enter a unique ID.
| ||
timestamp | Enter 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
- Enter the script below with the following updated parameters:
Parameter | Description | ||
---|---|---|---|
| |||
| |||
| |||
apiKey | Enter the Key ID generated from AMP. | ||
secretKey | Enter the Secret Key generated from AMP. | ||
nonce | Enter a unique ID.
| ||
requestPath | |||
requestBody | |||
timestamp | Enter a unix time stamp within 5 minutes of current time. | ||
httpMethod | Enter 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:
- 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).
- You must have the following permissions enabled:
...