# Panther API

## Overview

Panther offers a [REST API](https://docs.panther.com/panther-developer-workflows/api/rest) and a [GraphQL-over-HTTP API](https://docs.panther.com/panther-developer-workflows/api/graphql). You can use the [API Playground](https://docs.panther.com/panther-developer-workflows/api/api-playground) in the Panther Console to explore both APIs. Before making API calls, you will need to [generate an API token](#how-to-create-a-panther-api-token).

Discover the [REST API schema here](https://docs.panther.com/panther-developer-workflows/rest#discover-the-panther-rest-api-schema), and the [GraphQL schema here](https://docs.panther.com/panther-developer-workflows/graphql#discover-the-panther-graphql-schema).

### Supported operations

The Panther APIs support an ever-growing set of operations that allow you to build your security workflows:

| <p><a href="api/rest">REST API</a></p><ul><li><a href="api/rest/alerts">Alerts</a></li><li><a href="api/rest/alert-comments">Alert Comments</a></li><li><a href="api/rest/api-tokens">API Tokens</a></li><li><a href="api/rest/data-models">Data Models</a></li><li><a href="api/rest/globals">Globals</a></li><li><a href="api/rest/log-sources">Log Sources</a></li><li><a href="api/rest/queries">Queries</a></li><li><a href="api/rest/roles">Roles</a></li><li><a href="api/rest/rules">Rules</a></li><li><a href="api/rest/scheduled-rules">Scheduled Rules</a></li><li><a href="api/rest/simple-rules">Simple Rules</a></li><li><a href="api/rest/policies">Policies</a></li><li><a href="api/rest/users">Users</a></li></ul> | <p><a href="api/graphql">GraphQL API</a></p><ul><li><a href="api/graphql/alerts-and-errors">Alerts & Errors</a></li><li><a href="api/graphql/cloud-account">Cloud Account Management</a></li><li><a href="api/graphql/data-lake-queries">Data Lake Queries</a></li><li><a href="api/graphql/log-source">Log Source Management</a></li><li><a href="api/graphql/metrics">Metrics</a></li><li><a href="api/graphql/token-rotation">Token Rotation</a></li><li><a href="api/graphql/user-management">User & Role Management</a></li></ul> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## How to create a Panther API token

{% hint style="info" %}
After you have successfully created an API token, remember to periodically rotate it. See instructions for token rotation in [Rotating API tokens](#rotating-api-tokens), below.
{% endhint %}

1. In the upper right corner of your Panther Console, click the gear icon. In the dropdown menu, click **API Tokens**.
2. 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.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-6511f9015708889e31e3d89330e242c7add6f347%2Fcreate-api-token.png?alt=media)
   * If a token already exists, click **Create New Token**.
3. Provide a **Name**, then choose the permissions you'd like to grant this token.
   * You can find required permissions for each [REST API](https://docs.panther.com/panther-developer-workflows/api/rest) operation on each entity's page.
   * See the [required permissions per Panther Analysis Tool (PAT) command here](https://docs.panther.com/detections-repo/pat/pat-commands#permissions-required-per-command).
4. 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.
5. Click **Create API Token**.
   * You will see a success screen that displays the value of the API token. Copy the API token and store it in a secure location, as it will not be displayed again.
   * Optionally [validate that new API token works](#validating-your-api-token).

<figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-4423f59a4073abef61f1299ccef13eb76908cf7e%2Fapi-token-success.png?alt=media" alt="The image shows the success screen after you create an API Key. At the top, it says &#x22;API Key Created&#x22;. 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 &#x22;Done.&#x22;" width="375"><figcaption></figcaption></figure>

### Validating your API token

{% hint style="info" %}
There may be a propagation delay of 30 to 60 seconds after adding an API token.
{% endhint %}

After generating an API token, you can validate that it's working in either the API Playground or using PAT:

{% tabs %}
{% tab title="API Playground" %}
To test your API token in the API Playground in the Panther Console:

1. On the API token creation success screen, click **Give it a go on our Playground**.
2. At the bottom-left corner of the Playground screen, locate the **REQUEST HEADERS** tab. 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. In the upper left corner, press the "play" icon to run the test.

<figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-582a7060d464c576c0aed9616742b86a09c434f0%2Fapi-playground-test.png?alt=media" alt="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 &#x22;Request Header&#x22; is circled. On the right, there is a section labeled &#x22;Documentation Explorer&#x22;." width="563"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="PAT" %}
{% hint style="warning" %}
You must [have PAT installed](https://docs.panther.com/panther-developer-workflows/detections-repo/pat/install-configure-and-authenticate-with-pat) to perform this test.
{% endhint %}

To test your API token using [PAT](https://docs.panther.com/panther-developer-workflows/detections-repo/pat) in the CLI:

* Run `pipenv run pat check-connection --api-token <your-api-token> --api-host <your-api-host>`.
  {% endtab %}
  {% endtabs %}

### 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 tokens periodically may lessen the likelihood of them 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 an API token in your Panther Console or by calling Panther's API itself. Once you've rotated your token, the previous one is no longer valid.

{% tabs %}
{% tab title="Panther Console" %}
**Rotate an API token in the Panther Console**

To rotate your API token in the Panther Console:

1. In the upper right corner of your Panther Console, click the gear icon, then **API Tokens**.
2. Locate the token you'd like to rotate. In the upper right corner of its tile, click the three dots icon, then **Rotate**.

   <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-a17f7880972eb50956000279065985b90c4009fb%2FScreenshot%202023-03-20%20at%204.04.13%20PM.png?alt=media" alt="The API Tokens page in the Console shows a token called &#x22;Example Key.&#x22; 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."><figcaption></figcaption></figure>
3. 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.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-e7fe0900e45eccbd7a71179e4071eaee7c82302a%2FScreenshot%202023-03-20%20at%204.08.06%20PM.png?alt=media)
4. 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."](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-67d6889800e340412502f08b6b1eca823fa12183%2FScreenshot%202023-03-20%20at%204.09.52%20PM.png?alt=media)
   {% endtab %}

{% tab title="REST API" %}
**Rotate an API token using the Panther REST API**

You can rotate your API tokens using the Panther REST API. An API token rotates itself using the `POST api-tokens/self/rotate` endpoint. Learn more on [API Tokens](https://docs.panther.com/panther-developer-workflows/api/rest/api-tokens).
{% endtab %}

{% tab title="GraphQL API" %}
**Rotate an API token using the Panther GraphQL API**

You can rotate your API tokens using the Panther GraphQL API, with the `rotateAPIToken` operation. Learn more about how to use this endpoint on [Token Rotation](https://docs.panther.com/panther-developer-workflows/api/graphql/token-rotation).
{% endtab %}
{% endtabs %}

## Troubleshooting the Panther APIs

Visit the Panther Knowledge Base to [view articles about the Panther APIs](https://help.panther.com/Panther_Developer_Workflows/Panther_API) that answer frequently asked questions and help you resolve common errors and issues.