Introduction
With the GraphQL API you can access data for quests (simulations), threats and incidents. The API enables users to query a strongly typed API and get exactly the data that 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:
-
Choose an existing admin user (personal account) and retrieve the token from there.
-
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:
-
Choose an existing admin user of one of your partners (personal account) and retrieve the token from there.
-
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.
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.
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.
- See the API documentation at this page.
- See the following guide about using an GQL client to explore Hoxhunt incidents.
- Manage incidents using Hoxhunt's GQL API
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.