> ## Documentation Index
> Fetch the complete documentation index at: https://kb.mspprocess.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

**1. 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.

**2. Copy the key**

Copy the key, which starts with `petra_`. Petra shows it only once.

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

## Connect it in Triggr

**1. Open the configuration**

Go to **Integrations > Petra Security** and click **Configure** on the Base Configuration card.

![The Base Configuration card with Status Not Configured, Admin Consent Not Required and a Configure button.](https://mintcdn.com/triggr/nyuVXZ1rouDTTEvu/images/integrations-common/base-configuration.png?fit=max\&auto=format\&n=nyuVXZ1rouDTTEvu\&q=85\&s=bb81acb082055015f91beda7b4876f35)

**2. Enter the key**

Paste the key into API Key and click Save Configuration.

![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.](https://mintcdn.com/triggr/nyuVXZ1rouDTTEvu/images/petra-security/configure.png?fit=max\&auto=format\&n=nyuVXZ1rouDTTEvu\&q=85\&s=12421420a28da6d64f356d79162f7455)

## 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

> [accordion] 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] 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] An action fails with 400
>
> Petra rejected a date. Use `YYYY-MM-DD` or a UTC date-time ending in `Z`.

> [accordion] 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.


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