> For the complete documentation index, see [llms.txt](https://docs.threatdefence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.threatdefence.com/siem-integrations/sso-and-identity/petra-security.md).

# Petra Security

Connect Petra Security to ThreatDefence so our SOC can monitor account compromise in your Microsoft 365 tenants around the clock, follow each incident through to remediation, and correlate it with your other security sources.

The integration uses the Petra public API with one API key, created by a Petra Admin in Step 2. It collects incidents, posture reports and daily failed attack summaries.

On the first run, ThreatDefence collects the last 30 days. Daily failed attack summaries for that period catch up over the first hour.

ThreatDefence only **reads** from the Petra API. Nothing in your Petra or Microsoft 365 configuration is changed.

{% hint style="info" %}
**Before you begin:**

* Sign in to Petra at [app.petrasecurity.com](https://app.petrasecurity.com) with the **Admin** role. Only Admins can create API keys; Full Members can see the key list but can't create keys.
* Decide which tenants ThreatDefence should monitor. You list them in Step 1.
* Check whether Petra is your own or run by your IT provider. If a provider runs it, see [Petra run by a provider](#petra-run-by-a-provider).
  {% endhint %}

***

### Step 1: Find your tenant IDs

ThreatDefence collects only the tenants you list. You can give each tenant by either ID:

* **Petra tenant ID**: open the tenant in the Petra dashboard. The ID is the last part of the browser address: `app.petrasecurity.com/tenant/<Petra tenant ID>`.
* **Microsoft tenant ID**: the **Tenant ID** shown on the **Overview** page of the Microsoft Entra admin center.

For several tenants, separate the IDs with commas.

***

### Step 2: Create the ThreatDefence SIEM API key

Create a key that only ThreatDefence uses. Petra limits how many requests each key can make, so a key shared with another tool slows down collection for both. Petra API keys have no permission settings and don't expire.

1. In Petra, go to **Settings** and open the **API Keys** tab.
2. Select **Create API Key**.
3. Enter a description such as **ThreatDefence SIEM**, then select **Create API Key** in the dialog.
4. Copy the key. Petra shows it only once, and you can't retrieve it after you close the dialog.

{% hint style="warning" %}
A Petra API key can read every tenant in the Petra organization it was created in. ThreatDefence collects only the tenant IDs you enter in Step 3, so make sure that list contains only your own tenants.
{% endhint %}

***

### Step 3: Add the integration in ThreatDefence

Please follow the [Managing Integrations](https://docs.threatdefence.com/platform-management/managing-integrations.md) instructions and onboard the **Petra Security** integration. You'll need:

* **Petra tenant IDs**: the tenant IDs from Step 1, separated by commas
* **Petra API key**: the key from Step 2

If you encounter difficulties with onboarding, please email the credentials to <support@threatdefence.com>.&#x20;

{% hint style="warning" %}
Don't send API keys by email or chat. If you can't use the platform form, ask your ThreatDefence contact for a one-time secure upload link.
{% endhint %}

#### Petra run by a provider

If an IT provider runs Petra for you, your tenants may sit in the provider's Petra organization, and only the provider's Admins can create a key. A key from that organization can read every client the provider manages, not only you. Ask the provider for a key created for ThreatDefence only. Then enter only your own tenant IDs in Step 3, and check the list with the provider.

#### Rotating or revoking the key

Petra API keys don't expire, so rotate the key on your own schedule, and whenever someone who had it leaves.

* **Rotate**: create a new key as in Step 2, paste it into the ThreatDefence integration, then delete the old key in Petra. Collection resumes from where it stopped and catches up on gaps of up to 90 days.
* **Revoke**: in **Settings → API Keys**, select the trash icon next to the key and confirm. Deletion takes effect immediately and can't be undone, and collection stops straight away.

#### Troubleshooting

| Symptom                        | Likely cause                                                            | Fix                                                                                                  |
| ------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| No data after onboarding       | The key was copied incompletely, or a tenant ID is wrong                | Paste the key again and check each tenant ID against Step 1                                          |
| One tenant is missing          | Its ID isn't in the list, or the tenant isn't in the key's organization | Add the tenant ID, or create the key in the Petra organization that holds it                         |
| Data stopped after a date      | The key was deleted in Petra                                            | Create a new key and update the integration                                                          |
| No posture reports             | No posture report has been completed for the tenant yet                 | Run one in Petra under **Reporting → Posture Report**; completed reports are collected automatically |
| No failed attack summaries yet | Each day's summary is collected six hours after the day ends (UTC)      | No action needed: the first summaries appear within the first hour, and new ones daily               |

***

## Support

For questions or assistance, please contact:\
📧 **<support@threatdefence.com>**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.threatdefence.com/siem-integrations/sso-and-identity/petra-security.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
