Agent API Keys

tCell agents use API keys to control authentication and access control for all communications from tCell agents to the tCell cloud. This guide describes:

  • scopes and permissions
  • how to configure API keys
  • how to configure the agents
  • setup and management considerations

Scopes and Permissions

The agent API keys have two scopes:

  • Server Agent
  • JS Agent

Server Agent is for any agent that is on the server side, whether Web Server Agents, or Application Server Agents.

The JS Agent is the client side agent that runs inside the browser.

In addition, each agent key has an application scope. An application scope indicates which application the key can be used for. A key can have one or more applications under its application scope. In addition, it can be a "Master Key" which indicates it is valid for all applications for a given account.

For simplicity, use the master key to get started. However, if you have several applications under management, it is recommended to follow the principle of least privilege and only provide the application scope needed for a given key (ideally a single app)

For the JS Agent, there is a pre-created key called "Default JS Agent Key." This is a master key provided for convenience, and can be removed once more tightly scoped keys are created.

Configuring API Keys

An admin can create and configure API keys. This can be done as follows:

  1. Login via insight platform to the tCell console.
  2. Navigate to the tCell Admin → API Keys tab in the console.
  3. Choose "Add New Key"
  4. Name the key (ideally, it incorporates the name of the app, whether it is Server or JS Agent, and if it's a master key)
  5. Select Scope - If this is for Server Agent, then select "Server Agent," likewise for "JS Agent"
  6. Choose the application(s) that one wants this key to have access control privileges for.

Below is an example of a Server Agent key with permissions for "app1-egsTG" and "app2-Lu1mp": Scoped key

Below is an example of a key created as a master key: Master key

In addition to creating keys, one can edit existing keys-for example, to change the application privileges–by choosing the edit icon for an existing key in the "API Keys" tab.

Configuring the Agent

As mentioned, every agent has an API Key used to communicate from agent to the tCell cloud. This is configured in the "Download Agent" tab within the overall Admin window. Downloading the agent here will provide a config file with the API key configured for a given application.

In addition, there is a convenience selection when selecting the key. "Create New API Key" This will generate a master server agent key with the application name and user name. For production instances, it's recommended to create the API key in the API key section, and select it when downloading the config file.

In addition, anything defined in a config file, can also be defined via environment variables. See Server Agent Options for more details.

In a container environment, the typical practice is to use environment variables rather than a config file, so when one downloads the config file as mentioned above, one can set the equivalent environment variables accordingly.

Setup and Management Considerations

As mentioned prior, the keys can be scoped to specific application or applications, as well as having global permissions to all applications as a master key.

Having global permissions allows for ease of use, especially getting started, however, the recommended approach for production instances especially is to have each key (Server Agent, and JS Agent) scoped to a specific application. This follows the security principle of least privilege.

This limits the exposure if a key is accidentally exposed. And also this makes it easy to create and roll out a new key, since the rollout will only need to be done to a single application and not all applications using tCell.