> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# BigPanda

> Connect BigPanda to Serval with a single API token so workflows can manage incidents, alerts, environments, and more through the BigPanda API.

## About BigPanda

BigPanda is an AIOps and incident intelligence platform that correlates monitoring alerts into incidents. The Serval BigPanda integration connects with one API token: an admin pastes a BigPanda Bearer token, and Serval makes calls to the BigPanda API on your workflows' behalf through the built-in **BigPanda API request** action. Serval automatically routes each call to the correct BigPanda API host and attaches your token, so there is nothing technical to configure beyond pasting the token.

**Authentication:** API token (a BigPanda Bearer token - a User API Key, a Service Account Key, or the org-wide Org Token)

**Data sync:** On-demand only. Connecting BigPanda does not import incidents, alerts, or any other records into Serval, and there are no background syncs, webhooks, or auto-installed workflows - all access happens when a workflow runs a BigPanda action.

## What the BigPanda integration enables

| Capability                         | Description                                                                                                                                                                                                |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Incident management                | List and retrieve incidents by environment, add comments, resolve, snooze, assign, merge, and split incidents, batch-resolve alerts, read incident activity, and manage incident tags and tag definitions. |
| Alert ingestion and retrieval      | Send alert monitoring events into BigPanda, send normalized alerts to Open Integration Manager integrations, and retrieve raw integration alerts.                                                          |
| Environments and groups            | Create, list, update, and delete environments and environment groups.                                                                                                                                      |
| Changes and root cause correlation | Create, update, and retrieve change records, and manage related-change correlations.                                                                                                                       |
| Alert enrichment                   | Manage alert enrichments, enrichment configuration and tags, mapping enrichments and map uploads, and check enrichment job status.                                                                         |
| Correlation patterns               | Create, list, update, delete, and reorder correlation patterns.                                                                                                                                            |
| Maintenance plans                  | Create, list, update, and stop maintenance plans, including ordered plans and planned maintenance schedules.                                                                                               |
| AI analysis                        | Trigger or read AI analysis for an incident and manage AI analysis configurations.                                                                                                                         |
| Inbound integration configuration  | Manage Open Integration Manager and email parser configurations, data connectors, and BigPanda integrations themselves.                                                                                    |
| Administration                     | Manage SCIM users, roles, API keys and service-account API keys, and read audit logs, topology models, and troubleshooting logs.                                                                           |

Anything in the integration's modeled surface of the [BigPanda API](https://api-docs.bigpanda.io/) can be accessed through Serval. This covers both the primary REST API (`api.bigpanda.io`) and the Open Integration Manager / ingestion endpoints (`integrations.bigpanda.io`).

## Get your credentials

Serval accepts any BigPanda Bearer token. For most teams, that means a BigPanda API key - either a **User Key** (tied to your BigPanda user and its roles) or a **Service Account Key** (shared, not tied to a person). If your workflows focus on sending alert data into BigPanda, you may need the org-wide **Org Token** instead - see the gotchas below for which endpoints document which token type. See BigPanda's [API Key Management](https://docs.bigpanda.io/en/api-key-management) guide for full details.

<Tabs>
  <Tab title="API key (recommended)">
    <Steps>
      <Step title="Sign in with the right permissions">
        Sign in to BigPanda as a user whose role grants the "API Keys" permission with Full Access (configured under Roles Management).
      </Step>

      <Step title="Open API Keys">
        Open the **API Keys** page in BigPanda Settings and select the **New key** button.
      </Step>

      <Step title="Choose the key type">
        Select **User Key** (carries your user's roles and permissions) or **Service Account Key** (shared, not tied to a person - best for team automation).
      </Step>

      <Step title="Fill in the key details">
        Enter a Key Name, choose a key expiration (6 months, 12 months, 24 months, or no expiration), select a user to notify before expiration, and optionally add a description (up to 1000 characters).
      </Step>

      <Step title="Create and copy the key">
        Select **Create Key** and copy the key immediately.
      </Step>
    </Steps>

    <Warning>
      BigPanda displays a new API key exactly once and does not store a copy. If you lose it, you must create a new key and reconnect.
    </Warning>
  </Tab>

  <Tab title="Org Token">
    <Steps>
      <Step title="Sign in as an administrator">
        Sign in to BigPanda as an administrator with integrations access.
      </Step>

      <Step title="Open the Integrations tab">
        Open the **Integrations** tab in BigPanda.
      </Step>

      <Step title="Find your Org Token">
        Your org's Bearer token appears in the example headers of any Alerts API integration's instructions. See BigPanda's [Authentication and Headers](https://docs.bigpanda.io/en/authentication-and-headers) guide.
      </Step>
    </Steps>

    <Note>
      The Org Token is org-wide. BigPanda documents it as the required token type for sending alert monitoring events, the legacy v1 incident endpoints, the alert filter plan and schedule endpoints, and the Open Integration Manager and email parser configuration endpoints. For everything else, a User Key or Service Account Key is the better choice - it gives better audit logging and scoped permissions.
    </Note>
  </Tab>
</Tabs>

<Tip>
  Serval does not track your BigPanda key's expiration date. Set a notification user when creating the key so someone is warned before it expires, and rotate it in Serval when it does.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open the BigPanda integration">
    In Serval, open the **BigPanda** integration's connect form.
  </Step>

  <Step title="Paste your token">
    Paste your BigPanda Bearer token into the **API Token** field (a masked password field). The form recommends a User API Key for better audit logging and scoped permissions, but an Org Token also works.
  </Step>

  <Step title="Submit">
    Submit the form to finish connecting.
  </Step>
</Steps>

<Note>
  Serval's BigPanda integration targets BigPanda's US API hosts (`api.bigpanda.io` and `integrations.bigpanda.io`). The hosts are fixed - there is no field to select a region, and EU-hosted BigPanda orgs are not supported. If your organization is hosted in BigPanda's EU environment, contact Serval support before connecting.
</Note>

<Note>
  Serval performs no validation on the API Token field when you connect - the field is not marked required, there is no format check, and no test call is made. A mistyped or expired token will not produce an error here; it surfaces later as failed workflow runs.
</Note>

When you reopen the connection settings, the stored token is shown obfuscated (bullet characters plus its last 4 characters). Saving the form with the field blank or still obfuscated keeps your existing token unchanged - you only need to paste a new value when rotating the token.

## Verifying the connection

The BigPanda integration ships no in-product health checks - no health checks section appears on the integration settings page, and connection problems surface as failed workflow runs instead.

To confirm your token works, run a workflow that uses the **BigPanda API request** action to make a simple read-only call - listing your BigPanda environments is a good lightweight choice - and check that the run succeeds.

<Tip>
  If a simple read-only call succeeds but a specific call fails with a 401 or 403 error, the connection is fine - the stored token's type or its user's BigPanda permissions do not cover that particular API. See the gotchas below.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Some calls fail with 401 even though others work">
    Serval stores exactly one token and sends it on every call, but BigPanda documents different required token types per API family. Most resource APIs - incidents, environments, changes, enrichment, correlation patterns, maintenance plans, and the administration endpoints - document the User API Key type. The endpoint for sending alert monitoring events, the legacy v1 incident endpoints, the alert filter plan and schedule endpoints, and the Open Integration Manager and email parser configuration endpoints document the org-wide Org Token instead. If your workflows mix families that need different token types, calls outside your stored token's family fail with 401 - reconnect with the other token type, or split usage across connections. Open Integration Manager ingestion calls also reference a BigPanda integration app key created during BigPanda inbound-integration setup; the Bearer token alone is not sufficient there.
  </Accordion>

  <Accordion title="Permission errors on specific calls with a User Key">
    A User Key carries all roles and permissions of its associated BigPanda user, so endpoint-specific 401/403 errors usually mean the key's user lacks the relevant BigPanda permission. For shared automation that should not depend on one person's account, create a Service Account Key instead and reconnect with it.
  </Accordion>

  <Accordion title="An expired or bad token shows up as failed workflow runs">
    Because there is no data sync and no in-product health check, nothing alerts you proactively when the token expires or is revoked - the first symptom is failed workflow runs. Key expiration (6, 12, or 24 months, or none) is managed entirely in BigPanda; rotate the key there and paste the new value into the Serval connection.
  </Accordion>

  <Accordion title="Lost the API key">
    BigPanda shows a newly created API key exactly once and does not store a copy. If you lose it, create a new key in BigPanda and update the Serval connection with the new value.
  </Accordion>

  <Accordion title="One token, two API hosts - routing is automatic">
    BigPanda serves most of its API from its primary host (`api.bigpanda.io`) but serves Open Integration Manager configuration, email parser configuration, data-connector settings, and normalized-alert ingestion from a second host (`integrations.bigpanda.io`). Serval routes each call to the right host automatically and sends the same Bearer token to both - you never specify a host yourself. Both hosts are BigPanda's US endpoints; EU-hosted orgs are not supported.
  </Accordion>

  <Accordion title="Editing the connection never wipes the token">
    The settings form shows the stored token obfuscated (bullets plus the last 4 characters) with a pencil icon for entering a replacement; canceling the edit restores the obfuscated value. Submitting the form with the field blank or still obfuscated keeps the existing token - you only need to re-paste a token when rotating it.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your BigPanda integration.