Manage API Keys

API keys are required to authenticate use of the SmashFly Contact Export API and SmashFly List Lookup API. (This type of authentication is different from the authentication used for the Contact Import and Jobs APIs, both of which leverage end user credentials for authentication.)

The Contact Export and List Lookup APIs enable the extraction of contact and contact list information from the SmashFly Console. Thresholds for the amount of data that can be extracted are defined in a Customer SLA, which must be signed before your organization can use the Contact Export API or List Lookup APIs in a Production environment. Extracting data beyond the thresholds defined in your organizations SLA may result in additional charges.

Note: If your organization does not have access to the Developer's Corner, you can request information about the Export API SLA from your SmashFly Customer Success Manager.

When the Developer's Corner is available to your organization, users who have the  Configuration System and Developers' Corner privilege can create and manage API keys for the Contact Export and List Lookup APIs under Configuration > Developers' Corner > Manage API Keys.

You can find documentation for all SmashFly APIs at http://www.smashfly.com/developers.

API Keys

API keys for the Contact Export and List Lookup APIs should be generated by the SmashFly System Administrator at your organization — not by SmashFly Support, Services, or your Customer Success Manager. API keys are active for a limited period of time, which is defined when the key is generated; the maximum expiration date is 1 year from the time of key generation.

Note: The API key does not currently impose limitations on the data that can be exported from a zone. For this reason, you must take great care when generating and transmitting API keys. When transmitting a key to the individual who will use it, SmashFly recommends using data encryption or verbal communication.

Generating an API Key

Once the Developer's Corner is available in your zone, take the following steps to generate an appropriate API key.

  1. Log in to the SmashFly Console as a user who belongs to a privilege group that includes the Configuration System and Developers' Corner privileges.
  2. Navigate to Configuration > Developers' Corner > Manage API Keys.
  3. Click + Generate New Key. The Generate New Key pop-up displays.

  4. Complete the fields on this pop-up:
    1. From the Scope list, select the API for which you are generating the key: List API or Contact API. (If you want to generate keys for both, you must repeat the instructions in this procedure for the second API key.)
    2. In the Contact Email field, enter the email address of the individual who will own this key. This individual will receive notifications when the expiration date for the key is approaching and should be directed to contact your internal SmashFly System Administrator to create a new key if another one is needed.

      Note: Each email address can have only a single key active for each API at a time. One email address can be assigned active keys for both the List API and the Contact API, but it cannot be assigned more than one key for a single API.

    3. From the Expiration list, select the appropriate expiration window for this key: 90 days, 180 days, or 1 year.
    4. In the Description field, enter text that describes for what they key will be used. (Only about 40 characters of the description will display on the Manage API Keys grid.)
  5. Click Generate. The system will display the API Key and an important note about copying it.

    IMPORTANT: Do not exit this screen before confirming that you have successfully copied and recorded the API key. For security reasons, once you leave this screen, you cannot retrieve that API key from SmashFly. (If you do not record or copy the key in a way that allows you to retrieve it, you will need to deactivate it and create another one to use the API.)

  6. Provide the key in a secure manner to the individual who will use it. Because of the level of access the API key provides, SmashFly recommends sharing the key only in a secure manner (for example, through a PGP encrypted file or orally/over the phone).

Deactivating an API Key

Once API keys are created, you can view the individuals who have keys and can deactivate them from the Manage API Keys page.

To deactivate an API key:
  1. From the Manage API Keys page, locate the row for the API key you want to deactivate and move the cursor over the green check mark in the Active column. A Deactivate tooltip displays.
  2. Click the check mark. A confirmation pop-up warns you that if you deactivate the key, you cannot reactivate it.
  3. Click Okay to deactivate the key. The check mark changes to a gray dash, indicating that the API key is no longer active (and can no longer be used for authentication).

Tips for Managing API Keys

  • If you created an API key in error, you can deactivate it at any time, as described in Deactivating an API Key
  • Inactive API keys cannot be reactivated. You must create a new API key, as described in Generating an API Key.
  • If an individual loses an API key, it cannot be retrieved through SmashFly. Your SmashFly System Administrator will need to deactivate the lost key and create a new one to replace it.
  • If an API key is about to expire, you can either let it expire and then generate a new API key for that scope, or you can deactivate the existing key and create a new one to replace it.