Set up GraphQL API

Introduction

With the GraphQL API you can access data for quests (simulations), threats and incidents. The API enables user to query a strongly typed API and get exactly the data and only the data is required for the task at hand. Read more at: https://app.hoxhunt.com/docs/graphql-external

 

API Token and setup

Setting up the GraphQL API for an internal team to use and maintain

To use the API a Hoxhunt Admin user needs to generate a GraphQL authentication token. The access tokens can be retrieved at https://admin.hoxhunt.com/account-settings/access-tokens

The API token is tied to individual admin users in the Hoxhunt system. This means that when an admin user is removed from the Hoxhunt system, the API integration will also be removed and will need to be reset with a new API token from another admin user.

You can choose to go about this in two ways:

  1. Choose an existing admin user (personal account) and retrieve the token from there.

  2. Setup a new user for this specific integration (for example hoxhunt.api@customer.com), make the user admin and then use that account to retrieve the API token.

Please review the options and choose the one more appropriate for your organization.

 

Setting up the GraphQL API for an external partner to use and maintain

The API token is tied to individual admin users in the Hoxhunt system. This means that when an admin user is removed from Hoxhunt, the API integration will also be removed and will need to be reset with a new API token from another admin user.

As you are working with an external partner, we would advise that you create users for your partners in your system (ex firstname.lastname@ext.brand.com), which can then be assigned the admin status is the Hoxhunt system. They will then be able to manage the API tokens independently, while also having access to the Response Product at https://response.hoxhunt.com.

You can choose to go about this in two ways:

  1. Choose an existing admin user of one of your partners (personal account) and retrieve the token from there.

  2. Setup a new user for this specific integration (for example hoxhunt.api@brand.com), make the user admin and then use that account to retrieve the API token and share it with your partner.

Please review the options and choose the one more appropriate for your organization.

 

Generate a token

1. Go to https://admin.hoxhunt.com/account-settings/access-tokens. You can also navigate here from the admin app located at admin.hoxhunt.com and click Account in the left-side navigation menu.

Admin_menu_account_settings.png

2. To generate a token, click Create a new token, enter the token description (this will show up in the list on the page) and confirm by clicking Create a new token

IMPORTANT: Copy the token before closing the page. You cannot retrieve the token later. If you forgot to copy the token, just delete the existing token and create a new one. 

Generate_GQL_auth_token.gif

 

Delete authentication tokens 

1. Go to https://admin.hoxhunt.com/account-settings/access-tokens.

2. Click Delete all or Delete and

3. Confirm the deletion in the pop-up.

 

Start using the Hoxhunt GQL API

There are various usage cases for the GQL API. You can use the API to explore data about incidents and the threats (reported emails) that they include and build API integration to integrate with 3rd party services such as SIEM or XSOAR solutions. 

 

Frequently asked questions

Who can generate GQL auth tokens?

All admin users in your organization can generate a GQL authentication token.  

When are tokens deleted?

All tokens are tied to the specific user that generated them.

  • A token is deleted when the user that generated the token manually deletes it themselves in the Admin Portal.
  • Alternatively, when the user that created the token is deleted (either by a Hoxhunt Admin in the Admin Portal, or if using SCIM in Azure Ad / OKTA) all the GQL authentication tokens generated by that users are also automatically deleted. This will mean that the GraphQL connection will be severe and a new API token must be generated to set it up again. 

 

Questions? 

If you have any questions about how to setup the GraphQL API, please don’t hesitate to reach out to your Customer Success Manager, Onboarding Manager, or our support team at support@hoxhunt.com.  

Was this article helpful?

2 out of 4 found this helpful

Have more questions? Submit a request