Skip to main content

API Keys

An Insights API key is the secret your SIP installation presents on every call it makes to Insights. The key tells Insights whose data the call is for. It stands for your whole organization, and nothing in the request can point it at anyone else's data, or narrow it to part of your own.

The key is created for you when your SIP instance registers, and your SIP holds it and uses it. There is normally nothing for you to do with one.

What the key authorizes​

Everything your SIP installation does to Insights, it does with this key:

  • Writing metric values, the device list and device records.
  • Creating and updating your user records, including which device groups each user is authorized for.
  • Updating client-level settings, such as your SIP installation's address.
  • Creating an Insights account for a user, and returning the URL that signs them in.

It is also the credential for the MCP server, where it grants the full tool set against your environment, and the caller names which of your synced SIP users to act as.

Treat it as an administrator credential. It isn't scoped to a person, a device group or a single job. Anyone holding it reaches all of your data, can act as any of your users, and can rewrite the user records that decide what your users see. Store it the way you would store an administrator password.

Where keys come from​

Two routes issue a key, and they differ in how long the key lasts.

Registration. When your SIP instance registers, the two sides exchange public keys, and Insights returns an API key encrypted with your SIP's public key. Your SIP repeats that exchange as needed, and each key it receives that way is valid for 24 hours. Connect Your SIP Instance covers the registration itself.

The Setup page. Generating a code there and exchanging it produces a key with no expiry. This is the older route, from before SIP created keys on its own, and it is how you get a long-lived key today — for an MCP client, for example.

The two look identical once issued. The key list shows an ID and a creation date, and nothing about expiry. So a key that works today and returns 401 tomorrow was a 24-hour key.

Insights never stores the key​

Insights only stores a SHA-256 hash of it. Keys are identified by that hash, which is enough to identify and revoke one, but the key itself can never be read back or shown again. If you lose one, issue a new one.

The key is held by whoever administers your FireMon installation, which is where an MCP caller gets it.

Reviewing and revoking keys​

The Setup page lists the keys that exist for your client, newest first, with the ID, the date it was created, and a delete action. It also has the Generate Code button, which produces the code that is exchanged for a long-lived key.

The page is at /setup, or https://insights.firemon.cloud/setup. Nothing in the Insights navigation links to it, so reach it by typing the path. It needs permission to view and modify client API keys, and the read-only role Insights gives to users synced from SIP doesn't have that permission.

Revoking a key that is in use breaks the connection. Revocation is immediate, with no grace period. Delete the key your SIP is holding and its calls to Insights start failing, so user records and settings stop being updated. Delete one an MCP client is using and that client starts getting 401. Insights asks you to confirm before deleting, so check the ID against the key you mean to remove first.

Unregistering does it to every key at once. When an administrator clicks Unregister in Administration > Settings > Insights, Insights revokes every key issued to your organization.