Frame Web API Overview

Frame’s web API service is based on standard RESTful HTTPS calls. All API endpoints require signed authentication via HTTP headers.

The typical workflow for an API call is as follows:

  1. Authenticate with the Frame Web API Gateway to sign the HTTPS API request.
    1. Create a signature with the client_id, the client_secret , and a timestamp (The client_id and client_secret are provided by Frame).
  2. Make the HTTPS REST call to the Web API resource endpoint using the client_id, timestamp, and the signature in the HTTP header (Created in step 1a).
  3. The Frame Web API Gateway verifies the signature of the HTTPS request and will then send the response of the previous call.

API Authentication

All Gateway API calls require authentication for each 3rd party service (use by individual users is not currently supported) and all API calls require signed requests for authentication.

Each API request must be signed and include the necessary information for proper signature verification. To sign an API request call, a client_id and client_secret are required to generate a signature and are also used for signature verification.

How to Provision API Credentials

  1. Navigate to the admin view of your Frame account.

  2. Locate the desired Account/Organization/Customer using the menu on the left. Click on the desired Account/Organization/Customer name and navigate to the “Authentication” tab listed under “Security.”

  3. Enable the API Authentication option and click “Save.” This will create a new tab entitled “API.”

    ../_images/overview_1.png
  4. Go to the newly created API Authorizations tab and click “Add API”.

    ../_images/overview_2.png
  5. Enter a name for the API Authorization and choose the Role(s) to grant the API Key at the bottom. Roles determine the permission level of the API. Click “Add.”

    ../_images/overview_3.png
  6. Click the ellipsis next to the API Authorization you just created and select “Manage Credentials.”

    ../_images/overview_4.png
  7. Name the API Key to create, then click the plus symbol to create it.

    ../_images/overview_5.png
  8. Record the “client_Id” and “client_Secret” to be used by your API calls.

    Warning

    Make sure to record this information, as it will only appear once. You will not be able to retrieve these details again.

    ../_images/overview_6.png

How to Make API Calls

In the last section, you generated a client_id and a client_secret.

The client_id is a unique string that Frame’s API uses for client/service identification. It is used by the authentication system to identify the proper account and API client permissions.

The client_secret is an HMAC-SHA256 key used to generate the signature and required by the signature verification process.

A signature is created by applying the HMAC-SHA256 algorithm on a string that is constructed from the client_id and a timestamp. The timestamp is the current time in seconds since epoch.

The proper steps for creating a signature are as follows:

  1. Get the current timestamp.
  2. Create a string by concatenating the timestamp with the client_id (timestamp + client_id).
  3. Apply HMAC-SHA256 on the newly created string using the client_secret.

In order to verify the signature, the API Gateway requires the newly created signature, the client_id, and the timestamp. The client_secret should NOT be included. This information should be sent in the HTTP request headers.

Below is a simple example of a python script that can be used to generate the signature needed for the API call and then make the API call.

#!/bin/env python

import hashlib
import hmac
import time
import requests
import base64

# Client credentials

client_id = "cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img-external-api-nfstg.mainframe2.com"
client_secret = "5891b5b522d5XXXXXXXXXXXXXXXXXXXXXXXXXX7163af34d08XXXXXe846f6be03"

# Create signature
timestamp = int(time.time())
to_sign = "%s%s" % (timestamp, client_id)
signature = hmac.new(client_secret, to_sign, hashlib.sha256).hexdigest()

# Prepare http request headers
headers = { "X-Frame-ClientId": client_id, "X-Frame-Timestamp": str(timestamp), "X-Frame-Signature": signature }

# Make request
r = requests.get("https://api-gateway-nfstg.mainframe2.com/v1/accounts", headers=headers)
accounts = r.json()
for account in accounts:
  print account