Managing API Keys

Fullstory’s HTTP APIs use API keys for authentication. If you are configuring an integration or building some tools of your own that make HTTP calls, you will need a key.

You can view and manage your API keys in the “API Keys” settings page, which allows you to:

• Create and delete keys
• Rename or change permissions for existing keys
• Use key suffixes to verify that your key value is correct

The “All Keys” tab shows you all the keys that you have permission to view. If you are an Administrator, then in addition to keys that you have created, you’ll also be able to see other users’ keys and legacy keys. If you are a Standard or Architect user, you will only be able to see your own keys.

Administrators who might be looking at a long list of keys can click the “My Keys” tab to view only their own keys, or the “Legacy Keys” tab to view any legacy keys.

Creating a Key

Standard and Admin Fullstory users may create API keys, and Architect users (available only for Enterprise plans) may also create API keys. You can create multiple keys, but for security reasons you should only create as many as you need, no more. To create a new API key:

1. Click the “Create key” button at the top-right corner of the keys list. The “Create API Key” sidecar will slide out from the right.
   
   
   
2. Enter a meaningful key name, and select the minimal permissions this key will need. If you don’t get these quite right, don’t worry--you can change them later.
3. Click “Save API Key.”
4. Upon successful creation of a key, a modal will appear with the new key’s value. You must copy the value from this modal at this time. You will not be able to see the key value again. Copy the value, save it in your preferred API key or password manager, and close the modal.
   

Identifying Keys with Suffixes

Sometimes you may have a key value in hand, and you want to verify that it is the right key or perhaps that it has the right permissions. You can verify the key by means of each key’s 7-character suffix.

To find your key’s suffix, look for the last occurrence of a forward slash character in the key. It should be followed by 7 alpha-numeric characters. These 7 characters are your key’s suffix. For example, in the screenshot above, the key value ends with the characters “/3BTYMQW”, so the suffix is “3BTYMQW.” You can then find a row in the keys table where the value in the “Suffix” column matches your suffix value.

Note that legacy keys do not have suffixes. You should have at most one legacy key, and it should be easily identifiable as such because the last 8 characters will not consist of a forward slash followed by 7 alpha-numeric characters.

Key Permissions

A key may be assigned “Admin”, "Architect" (if your plan has access) or “Standard” permissions. These three values exactly correspond to the “Admin”, "Architect" and “Standard” roles on the Users page.

Changing Key Attributes

You can change the name or permissions for keys that you have created. Click anywhere on the row for the key that you want to change (except the Delete button) to display the “Update API Key” sidecar. 

Change the name and/or key permissions, and click “Save API Key.” Changes will take effect immediately. The key value itself will remain unchanged, so updating the key attributes will not break any clients currently using the key.

Deleting Keys

To delete a key, click the “Delete” button that appears at the end of the row where the key is displayed. When you delete a key, API calls making use of the key value will stop working immediately.

Administrators may delete keys for all users. Standard and Architect users may only delete their own keys.

Legacy Keys

Previous versions of Fullstory provided only a single API key for each Fullstory org. When per-user API keys were added, Fullstory continued to support the older, per-org keys. These keys are called “legacy keys”. If you became a Fullstory customer after the new keys were released, you may not have a legacy key.

Legacy keys cannot be renamed or given fewer permissions. If you want a key with a better name or different permissions, create a new key and delete the legacy key. If you are not using your legacy key, you can delete it at any time.

Keep Your API Key Secure

It's important to treat your Fullstory API key with the same secrecy you use for your passwords. Publicly exposing your key can allow unauthorized access to the Fullstory API endpoints, and to your Fullstory data by a third party. Keep the following in mind to protect your key and your Fullstory account:

• Never embed API keys directly in code: API keys embedded in code are easily discoverable by the public. Instead of embedding your API keys in your applications, store them in environment variables or in files outside of your application's source tree.
• Do not store API keys in files inside your application's source tree: If you store API keys in files, keep the files outside your application's source tree to help ensure your keys do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub. Fullstory does participate in GitHub’s secret scanning program, but as of this writing it doesn’t cover private repositories.
• Use a separate key for each of your integrations or tools: A single-purpose key means you are better able to assign the key only the minimal permissions needed. In the event that the key is compromised, the API calls that can be completed with the key are also minimized. Also, when you roll the key value, you only need to update that value in one tool.
• Change your API keys from time to time: Refer to the “Created” date on your keys to determine their age. You can create new keys at any time. Update your applications to use the newly-generated keys, and then delete the old ones.
• Delete API keys that you are not using: The fewer active keys, the lower the risk that one of them may be compromised, particularly for keys that you are no longer using and are thus easily forgotten.

FAQ

What happens to an API key created by a user who is removed from an account?

An API Key is bound to the user that creates it. If that user is removed from the account, that API key will stop working as will the function it was being used to perform.