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

# Petra Security

> Connect Petra Security to Triggr with an API key from the Petra portal.

Triggr reads Microsoft 365 identity-threat data from Petra Security: tenants, incidents, failed attacks and usage. One key covers every tenant in your Petra organisation.

## Set up Petra Security

<Steps>
  <Step title="Create an API key">
    Sign in to the [Petra portal](https://app.petrasecurity.com) as an Admin, go to **Settings > API Keys** and click **Create API Key**. Enter a description such as `Triggr` and click Create API Key again.
  </Step>

  <Step title="Copy the key">
    Copy the key, which starts with `petra_`. Petra shows it only once.
  </Step>
</Steps>

See Petra's [API authentication guide](https://docs.petrasecurity.com/docs/api-reference/authentication).

## Connect it in Triggr

<Steps>
  <Step title="Open the configuration">
    Go to **Integrations > Petra Security** and click **Configure** on the Base Configuration card.

    <Frame>
      <img src="https://mintcdn.com/triggr/nyuVXZ1rouDTTEvu/images/integrations-common/base-configuration.png?fit=max&auto=format&n=nyuVXZ1rouDTTEvu&q=85&s=bb81acb082055015f91beda7b4876f35" alt="The Base Configuration card with Status Not Configured, Admin Consent Not Required and a Configure button." width="2272" height="330" data-path="images/integrations-common/base-configuration.png" />
    </Frame>
  </Step>

  <Step title="Enter the key">
    Paste the key into API Key and click Save Configuration.

    <Frame>
      <img src="https://mintcdn.com/triggr/nyuVXZ1rouDTTEvu/images/petra-security/configure.png?fit=max&auto=format&n=nyuVXZ1rouDTTEvu&q=85&s=12421420a28da6d64f356d79162f7455" alt="The Petra Security configuration window with an API Key field and its help text, an Allow insecure TLS switch under Advanced, and a Save Configuration button." width="1344" height="930" data-path="images/petra-security/configure.png" />
    </Frame>
  </Step>
</Steps>

## Tenant IDs and action inputs

Run List Tenants to get each tenant's `petraTenantId` and `microsoftTenantId`. The Petra ID is also in the portal URL: `app.petrasecurity.com/tenant/<petraTenantId>`.

| Action | Inputs |
| - | - |
| List Tenants | None. Includes paused tenants, not removed ones. |
| Get Usage Stats | `asOf` (optional, defaults to today) |
| Get Billable Users | `tenantId`: the Petra tenant ID (required) |
| Get Incidents | `tenantId`: Petra or Microsoft ID, blank for every tenant. `startDate` and `limit` (default 100, maximum 500) are optional. |
| Get Failed Attacks | `tenantId`: Petra or Microsoft ID (required). `startDate` and `endDate` are optional; the default is the last 30 days. |

Enter dates as `2026-03-01` or a UTC date-time ending in `Z`. Petra's [API reference](https://docs.petrasecurity.com/docs/api-reference/introduction) describes what each action returns.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Every action fails with 401">
    Check the key is pasted in full, starts with `petra_`, still exists under Settings > API Keys, and comes from the organisation that holds your tenants.
  </Accordion>

  <Accordion title="An action fails with 403 or 404">
    Use a tenant ID from List Tenants. Get Billable Users needs the Petra ID, not the Microsoft one.
  </Accordion>

  <Accordion title="An action fails with 400">
    Petra rejected a date. Use `YYYY-MM-DD` or a UTC date-time ending in `Z`.
  </Accordion>

  <Accordion title="Requests fail with 429">
    Get Billable Users and Get Failed Attacks allow one request a minute; other actions allow 10. Spread out calls when looping over many tenants.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.