Managing API Keys

Fullstory's Server API uses 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 at the API Keys settings page, which allows you to:

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

This article covers the following:

• Creating a key
• Key permission levels
• Managing your keys
• Keeping your API key secure
• Frequently Asked Questions

Creating a key

Each API key is created at a specific permission level. The permission level you can assign depends on your user role in Fullstory:

Architect role is only available on Enterprise plans. You can create multiple keys, but for security reasons you should only create as many as you need.

To create a new API key:

1. Navigate to Settings > Integrations > API Keys.
2. 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.
3. Enter a meaningful key name, and select the permission level for this key. The key name and permission level can be changed later.
4. Click Save API Key.
5. 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.

Key Permission Levels

API keys use three permission levels that form a hierarchy: Standard → Architect → Admin. A key at a higher level can access all endpoints available to lower levels.

• Standard — Send data into Fullstory (events, users), list sessions, view recording settings, and manage async operations.
• Architect — View, export, and delete user data. Access privacy settings, search exports, raw data exports, and manage extraction rules. Architect roles are available with Enterprise plans.
• Admin — Create, update, and delete element block rules that control what gets captured. Required for privacy-critical configuration changes.

To verify that a newly created key has the expected permission level, you can use the GET /me endpoint. See Testing API Key Permission Levels in the Server API documentation for details.

Managing your keys

The API Keys settings page lets you view all keys you have permission to see, identify keys by their suffix, update key attributes, and delete keys you no longer need.

Viewing your keys

The All Keys tab shows you all the keys that you have permission to view. If you are an Administrator, you can see all users' keys as well as 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.

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 permission level. 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.

Changing key attributes

You can change the name or permission level 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 permission level, 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.

Keeping 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 permission level 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.

Frequently Asked Questions

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.

What are legacy keys?

Previous versions of Fullstory provided a single API key per org. When per-user API keys were introduced, Fullstory continued to support these older, per-org keys—now called legacy keys. If you became a Fullstory customer after per-user keys were released, you may not have a legacy key.

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