You can extend the power of Guard Detect by integrating directly with the Atlassian platform GraphQL API. The API gives you access to all sorts of Atlassian data, so you can receive and manage alerts outside of Guard Detect.

The GraphQL API reference provides a comprehensive guide to Guard Detect queries and mutations. You can use the API explorer to get acquainted with the GraphQL API.

Authentication

Refer to the GraphQL authentication reference for all the available authentication options.

User API tokens can also be used to authenticate scripts and simple integrations. These clients use the https://api.atlassian.com/graphql URL. You can generate the token from your Atlassian account. Read how to Manage API tokens for your Atlassian account

If you don’t use a token to authenticate, you may see a redirection message, which will redirect you to an alternative interface where browser sessions are supported.

Service account API credentials can be leveraged for long-term integrations as they are not linked directly to a particular Guard Detect user. Read how to Manage API tokens for a service account

When using service accounts to integrate with Guard Detect, grant the User and Admin user roles on the Guard Detect app to the service account.

Scoped API tokens can also be used to increase security by limiting the operations a token can perform on the ARI. Guard Detect supports the following scopes:

Scope	Description
`read:alert:guard-detect`	Read alerts and their details. Example: can be used by the Guard Detect Add-on for Splunk and other tools to fetch latest alerts.
`write:alert:guard-detect`	Update some alert fields. Example: update alert status.
`read:detection:guard-detect`	Read the list of detectors.
`write:detection:guard-detect`	Create and update custom detectors.
`read:detection-setting:guard-detect`	Read detection configuration settings.
`write:detection-setting:guard-detect`	Modify detection configuration. Example: enable or disable detections, add or remove exclusions.
`read:subscription:guard-detect`	Read subscriptions to WebHooks, Slack, and MS Teams.
`write:subscription:guard-detect`	Update or delete subscriptions to WebHooks, Slack, and MS Teams.
`write:redaction:guard-detect`	Redact content, individual and in bulk.
`write:restoration:guard-detect`	Restore previously-redacted content.

Refer to the GraphQL reference for the available queries and mutations and the scopes they require.

Atlassian resource identifiers

Most GraphQL queries require an Atlassian resource identifier (ARI). If you’re not sure how to assemble your ARI or where to find your Atlassian IDs, visit our Build your ARI page.

Example GraphQL query

To get you started, here's an example query that fetches data about a Guard Detect workspace.

Open the API explorer

Paste this code into the main query window:

1
2
query getWorkspace($workspaceAri: ID!) {
  shepherd {
    workspace(id: $workspaceAri) {
      __typename
      ... on ShepherdWorkspaceConnection {
        edges {
          node {
            ... on ShepherdWorkspace {
              id
            }
          }
        }
      }
    }
  }
}

Note that Shepherd is an internal name for Guard Detect functionality.

In the query variables window, paste this code:

1
2
{ "workspaceAri": "your-workspace-ari-here" }

Replace the string your-workspace-ari-here with your workspace ARI.
Press the execute query button (triangle icon) at the top of the screen. Details about your workspace will appear in the panel on the right.

Need help? Reach out on the Guard Detect community.