Knowledge BaseCommunityRelease NotesTry Panther
Search
⌃K
Links

Panther API

Use Panther's GraphQL API for alert, role, and user management, and data lake querying

Overview

Panther offers a public GraphQL-over-HTTP API, meaning you can write GraphQL queries and invoke the API using a typical HTTP request. For more information on GraphQL, see GraphQL's documentation.
For a list of supported operations, see Panther API Operations.

Understanding a GraphQL query

Click to expand GraphQL query example
The example query below is named ListAlerts. This query will return a list of alerts including every alert's id, title, severity and status based on the time range provided.
  • The input variable of type AlertsInput is used to filter the alerts based on certain conditions, such as createdAtAfter and createdAtBefore. Those conditions will provide a time range for the query.
  • The alerts field returns an object with edges and pageInfo. Each edge has a node field that contains the actual alert data, such as id, title, severity and status.
  • The pageInfo field contains information on pagination, such as hasNextPage and endCursor, which allows the user to loop through all the pages of alerts once hasNextPage becomes false.
query ListAlerts($input: AlertsInput!) {
alerts(input: $input) {
edges {
node {
id
title
severity
status
}
}
pageInfo {
hasNextPage
endCursor
}
}
}

How to use Panther's API

Step 1: Choose a method for invoking the API

You can create and modify Panther API queries using one of the following methods:

Step 2: Create an API token

  1. 1.
    Log in to your Panther Console.
  2. 2.
    In the upper right corner, click the gear icon. In the dropdown menu, click API Tokens.
  3. 3.
    Click Create an API Token.
    The image shows the API Tokens page in the Panther Console. The screen says "You haven't created any tokens yet" and there is a red circle around the "Create an API Token" button at the bottom.
    ​
  4. 4.
    Provide a Name, and choose the permissions you'd like to grant the token.
  5. 5.
    In the IP Restrictions section, in the CIDR Blocks field, enter one or more IP addresses to which you'd like to restrict usage of the token, if any.
    • Enter the IP address(es) in CIDR notation, e.g., 10.0.0.0/8 or 8.8.8.8/32.
    • If no IP addresses are specified, the token will be usable by any IP address.
  6. 6.
    Click Create API Token.
You will see a success screen that displays the value of the API token. Please note that the API token is sensitive information and it will not be displayed again; make sure you copy the API token and store it in a secure location.
The image shows the success screen after you create an API Key. At the top, it says "API Key Created". There is a drawing of two people holding up a green checkmark. The API Key in this screen shot is blurred out. Beneath the key there is a blue button labeled "Done."

Testing the API token

There may be a propagation delay of 30 to 60 seconds after adding an API token.
After generating an API token, you can test to verify that it works as expected:
  1. 1.
    On the API token creation success screen, click the link that says Give it a go on our Playground.
  2. 2.
    Locate the REQUEST HEADERS tab at the bottom-left corner of the Playground screen. Under this tab, change the default value of the X-API-Key header from <ENTER_YOUR_KEY_HERE> to the value of your API token.
  3. 3.
    In the upper left corner, press the "play" icon to run the test.
The image shows the API Playground from the Panther Console. At the top, a play icon button is circled. On the left, a code box contains an example query. Beneath that, the header "Request Header" is circled. On the right, there is a section labeled "Documentation Explorer".
You can discover the available queries, mutations, and fields by clicking Documentation Explorer on the right side panel of the Playground.
For additional ways to discover the schema, see Discovering the Schema.​
Once you have successfully created an API token, remember to periodically rotate it. See instructions for token rotation in Rotating API tokens, below.

Step 3: Invoke the API

Prerequisites

To invoke the API using an HTTP curl operation, you will need the following information:
  • The GraphQL endpoint to hit
    • The GraphQL API endpoint is tied to your Panther domain and the API URL format is https://api.{YOUR_PANTHER_DOMAIN}/public/graphql.
      • To find this URL In your Panther Console, click the gear icon in the upper right corner, then API Tokens:
        The page's title is "API Tokens." Below, is an API URL, with its value blurred out. In the upper right corner is a "Create New Token" button.
        ​
  • The auth-related header
    • The auth-related header is called X-API-Key and its value should always be a valid API token that you generated in the Panther Console.
  • A GraphQL query

Invoking the API

There are two ways to invoke a GraphQL-over-HTTP API:
  • Option 1: Install and use a GraphQL Client to abstract the transport-related complexities (recommended)
  • Option 2: Manually construct an HTTP call
GraphQL Clients
Construct HTTP Calls
While all GraphQL operations are essentially simple HTTP calls, the advantage of using a GraphQL client is that it is more user-friendly.
We recommend using:
Below you'll find some examples of how you would construct a GraphQL query to fetch the first page of alerts in your system:
NodeJS
Python
Golang
// npm install graphql graphql-request
​
import { GraphQLClient, gql } from 'graphql-request';
​
const client = new GraphQLClient(
'YOUR_PANTHER_API_URL',
{ headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
​
// `PaginateAlerts` is a nickname for the operation
const query = gql`
query PaginateAlerts {
alerts {
edges {
node {
id
title
severity
status
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
`;
​
client.request(query).then((data) => console.log(data));
# pip install gql aiohttp
​
from gql import gql, Client
from gql.transport.aiohttp import AIOHTTPTransport
​
transport = AIOHTTPTransport(
url="YOUR_PANTHER_API_URL",
headers={"X-API-Key": "YOUR_API_KEY"}
)
​
client = Client(transport=transport, fetch_schema_from_transport=True)
​
# `PaginateAlerts` is a nickname for the operation
query = gql(
"""
query PaginateAlerts {
alerts {
edges {
node {
id
title
severity
status
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
"""
)
​
result = client.execute(query)
print(result)
package main
​
import (
"context"
"fmt"
"github.com/hasura/graphql"
)
​
// Strongly-typed languages don't pair well with GraphQL
var query struct {
Alerts struct {
Edges []struct {
Node struct {
Id graphql.String
Title graphql.String
Severity graphql.String
Status graphql.String
}
}
PageInfo struct {
HasNextPage graphql.Boolean
Cursor graphql.String
}
}
}
​
client := graphql.
NewClient("YOUR_PANTHER_API_URL", nil).
WithRequestModifier(func(req *http.Request) {
req.Header.Set("X-API-KEY", "YOUR_API_KEY")
})
​
if err := client.Query(context.Background(), &query, nil); err != nil {
// Handle error
}
​
fmt.Println(query.Alerts.PageInfo.HasNextPage)
​
You can find all available operations of the API, as well as detailed end-to-end examples in the subpages of the current page. For a high level list, check out our supported operations.

Option 2: Manually Constructing HTTP Calls

An example request:
curl 'YOUR_PANTHER_GRAPHQL_API_URL' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {YOUR_API_KEY}' \
-d '{"query":"\n query Foo {\n alerts {\n edges {\n node {\n id\n }\n }\n }\n }","variables":{}}'
The query above returns the first page of all of your Panther alerts. If it's the first time you're using GraphQL, please note the following:
  • There's only one endpoint.
  • The HTTP operation is always a POST.
  • The API operations are defined in POST's body.
  • The body of the POST operation always contains the following keys:
    • query - a GraphQL string defining the GraphQL operation that should be executed
    • variables - an optional set of variables that will be passed along to the query
    • operationName - an optional "nickname" for this operation
  • You must always select a set of fields to return (if the operation returns data.)
Note: The only thing that would change from one GraphQL operation to another is the body of the HTTP POST.

Step 4: Discover the schema

There are three options to discover the GraphQL schema:
  • Option 1: Download the publicly available GraphQL schema file (quickest)
  • Option 2: Use Panther's API Playground (most user-friendly)
  • Option 3: Perform an introspection query against the GraphQL endpoint (best for tools and services)
Download GraphQL file
Panther API Playground
Introspection query

Option 1: Download the publicly available GraphQL schema file

​
You can download the latest version of the GraphQL schema file here.

Option 2: Use the GraphQL Playground

Panther's API Playground is a user-friendly way of browsing and discovering what's supported in our API. Please refer to our API Playground docs for information on how to use this as a discoverability mechanism.

Option 3: Performing an introspection query

An introspection query yields all the GraphQL API's entities in a format that most third-party libraries can parse. This discoverability option is useful if you want to make another library or service aware of the supported operations and types that the Panther API has. These libraries typically issue their own version of an introspection query, so they only need to be pointed to an API URL.
For security purposes, the introspection query is an authorized operation. This means that you'll need to add an X-API-Key header to your HTTP call with the value of an API Token in order for the introspection to work.
$ curl -H "X-API-Key: <API_KEY>" -d <INTROSPECTION_QUERY> <YOUR_PANTHER_API_URL>
The actual shape of the introspection query is customizable. You can ask for a limited set of entities or for all possible information about the schema. For example, a query such as the following would yield every single piece of schema information:
query IntrospectionQuery {
__schema {
queryType { name }
mutationType { name }
types {
...FullType
}
directives {
name
description
locations
args {
...InputValue
}
}
}
}
fragment FullType on __Type {
kind
name
description
fields(includeDeprecated: true) {
name
description
args {
...InputValue
}
type {
...TypeRef
}
isDeprecated
deprecationReason
}
inputFields {
...InputValue
}
interfaces {
...TypeRef
}
enumValues(includeDeprecated: true) {
name
description
isDeprecated
deprecationReason
}
possibleTypes {
...TypeRef
}
}
fragment InputValue on __InputValue {
name
description
type { ...TypeRef }
defaultValue
}
fragment TypeRef on __Type {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
}
}
}
}
}
}
}
}

​

Rotating API tokens

API tokens are used to authenticate against and authorize access to Panther’s public API. As with username and password credentials, you should store API tokens securely to protect them from bad actors. Rotating your token periodically may lessen the likelihood of it being compromised. The Center for Internet Security (CIS) and National Institute of Standards and Technology (NIST) recommend rotating API tokens every 90 days.
You can rotate your API token either in your Panther Console, or by calling Panther's API itself. Once you've rotated your token, the previous one is no longer valid.
Panther Console
Panther's API
Rotate an API token in the Panther Console
To rotate your API token in the Panther Console:
  1. 1.
    Log in to your Panther Console.
  2. 2.
    In the upper right, click the gear icon, then API Tokens.
  3. 3.
    Locate the token you'd like to rotate. In the upper right corner of its tile, click the three dots icon, then Rotate.
    The API Tokens page in the Console shows a token called "Example Key." It has info about who created and modified the token, as well as when it expires. The three dot menu is open, and three options are displayed: Edit, Rotate, and Delete.
  4. 4.
    On the confirmation modal that pops up, click Continue.
    A modal titled "Rotate Example Key" asks the user if they're sure they want to refresh the key. There are Cancel and Continue buttons.
    ​
  5. 5.
    The modal will display your new API token. You will only see this once, so be sure to copy and store it in a secure location.
    The key rotation modal displays the new API token. There is a note saying "Please copy it since we won't show it to you again."
    ​
Rotate an API token using Panther's API
You can rotate your API key by calling Panther's API, using the rotateAPIToken operation.
Learn more about how to use this endpoint on Token Rotation.

Supported operations and examples

The Panther API supports an ever-growing set of capabilities that allow you to build your security workflows, as well as an API Playground to test operations.

Examples for supported operations

See Panther API Operations for a list of supported API operations and examples.

Example: Getting your Panther Version

Use the following query to confirm your Panther version.
query PantherVersion {
generalSettings {
pantherVersion
}
}

Troubleshooting the Panther API

Visit the Panther Knowledge Base to view articles about the Panther API that answer frequently asked questions and help you resolve common errors and issues.
Previous
Managing Panther Content via GitHub Actions
Next
Panther API Operations
Last modified 5h ago