Client Key Best Practices

Your client key allows you make search queries, but also has the ability to delete data collections. These are our best practices for using client key securely in the way that we recommend.

Command Center Security

Everyone who has access to Command Center should have their own user account. This makes it easier to disable an account when someone exits the organization and control user permissions at a more granular level. Using a shared account means that credentials will be shared and you won’t be able to tell who is accessing and making changes within Command Center anymore.

Secondly, Admin level privileges should be restricted to only those who require access to the client key. This should be as few people as possible.

Centrally and Securely Stored

It is important that the client key not be shared with anyone who does not explicitly requiring it to perform their function and it should never be stored anywhere public.

It is our recommendation that the client key be stored in a central secret management system (such as Vault). The client key should only be stored here, so that the client key can be easily cycled without breaking any part of your platform.

Systems that require the client key should call the secret management system in order to use the client key. Systems such as:

  • Configuration files generation (upload, SAYT, etc)
  • Web servers making queries to GroupBy APIs
  • Processes responsible for uploading data to GroupBy

Key Rotation


Only someone who knows exactly what they are doing should ever create or delete client keys. Once a client key is deleted, it cannot be restored. If you need help with this, please reach out to GroupBy Support and we can help you out.

Once the client key is securely stored in a central location, it becomes trivial to cycle the client key regularly in order to ensure that someone with access to an old key. The frequency by which you cycle your client key will depend on your own security practices.

Only a user with access to the Admin section of Command Center will have permissions to cycle the client key. The steps to generate a new key are as follows:

  1. Within Command Center, navigate the Key Management page in the Admin section.
  2. Click the button labeled ‘Create new primary key’. An additional client key will be created. The old client key will still be there and be fully functioning.
  3. Update your client key in the secure central store with the new key.
  4. Test all your systems to ensure they are functioning as expected.
  5. Once you are confident that all systems are using the new key properly, delete the old client key within Command Center.
  6. Confirm that all your systems are working as expected with the new client key.