Connect Petra Security

Petra Security watches your customers' Microsoft 365 for signs that an account has been taken over. It reads the signals across Entra ID, Exchange, SharePoint and Teams, and reports the compromises that got through: business email compromise, stolen session tokens, malicious inbox rules, and the quiet changes an attacker makes to keep their access. It is built for MSPs, so one Petra organization holds all of your client tenants, and the alongside-it billing view tells you what each one costs you this month.

Connecting Petra Security to StackJack gives your AI assistant a small family of petra_ MCP tools — MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:

• Sweep for live compromises — pull the incident feed across your whole book at once, or narrow it to one client, with the remediation state, whether the incident is still live, how long the attacker has had access, and the affected user
• Report blocked attacks — the attacks Petra stopped for a client, broken down by country, by day and by attack type, with the people being targeted most and where their attackers came from
• Reconcile your Petra bill — every tenant's licensed and billable user counts, trial or active status, and this month's proration, in a single call
• Settle an invoice question — the individual billable users behind one client's count, with their licenses and account state
• List your client tenants — the roster behind everything else, including which tenants are paused

How StackJack authenticates to Petra Security

Petra Security uses a single API key. You mint it once in the Petra portal and paste it into StackJack — there is no client ID, no second secret, and nothing to renew on a schedule. The key stays valid until someone deletes it.

Two things about the key are worth knowing before you create it:

• Only a Petra Admin can create one. Full Members can see the list of keys but cannot mint one. If the API Keys page shows no create button, you are signed in with the wrong role.
• Petra shows the raw value once. It appears at creation and never again. Copy it straight away. If you lose it, delete the key and make a new one.

The key is scoped to your whole Petra organization, not to a single client. One key sees every tenant you manage in Petra, which is what makes the cross-tenant sweep possible. It also means the key is a sensitive credential: treat it like a password.

Steps

1. Sign in to the Petra portal with an account that has the Admin role.
2. Go to Settings, then API Keys, and create a new key.
3. Copy the key immediately. Petra will not show it again.
4. Open Petra Security in StackJack, paste the key into the API Key field, and save. There is no URL to enter — Petra has one address and StackJack already knows it.
5. Run a Test Connection. StackJack asks Petra for your tenant list, which proves both that the key works and that it is attached to the organization you expect.

What you get

Finding compromises

The incidents tool is the one to reach for first. Leave the tenant blank and it returns incidents across every client you manage, newest first — the "what is live across my whole book right now?" question. Name a tenant and it narrows to that client.

Each incident carries enough to triage it: whether it is still live, how long the attacker has had access, the remediation state, and the user involved. It also carries a direct link into the Petra dashboard, which matters because of the limit below.

Reporting to clients

The failed-attacks tool is the client-facing half. Where incidents are compromises that succeeded, failed attacks are the ones Petra stopped — and that is the material that justifies the spend in a quarterly review. It comes back as a summary rather than a raw event list: totals by country, by day and by attack type, plus the people being targeted most and the countries their attackers came from. You choose the reporting window, or let Petra default to the last 30 days.

Billing

Two tools cover billing, and it is worth knowing which to use. The usage tool returns every tenant's counts in one call: licensed users, billable users this month, proration, and whether the tenant is on a trial, active, not-for-resale or deleted. That is the tool for a monthly reconciliation. The billable-users tool returns the individual people behind one client's count, which is what you want when a client questions an invoice.

Things to know before you rely on it

Every Petra tool is read-only

Petra's API reports; it does not act. There is nothing StackJack can do through it to remediate an account, pause a tenant or start a scan — those live in the Petra dashboard. In practice this works well: your AI finds and explains the problem, then hands a person the link to fix it. But if you were expecting an assistant that remediates a compromise end to end, Petra cannot be that today.

Reports and incident detail are not in the API

Two things Petra markets are not reachable programmatically:

• The white-labeled PDF reports — Threat Remediation, Tenant, Prospecting, Posture, User Activity and Domain Spoofing — are produced in the dashboard only.
• The forensic detail behind an incident — the attacker timeline, what they touched in the mailbox, and the analyst's summary — is also dashboard-only. The incidents tool returns the incident and a link to it, not the investigation.

Petra is strict about how fast you ask

Petra allows 10 requests a minute to each of its endpoints. That is low, and it shapes how you should ask for things:

• Two tools cover one client per call: billable users, and failed attacks. Asking for all of them across sixty clients takes about six minutes of waiting. That is Petra's limit, not a StackJack delay.
• Where a whole-organization view exists, prefer it. The usage tool gives you every tenant's billing counts in one request, and the incidents tool covers every tenant when you do not name one.

StackJack paces requests and backs off automatically, which usually makes a large report slower rather than failed. Pacing smooths a burst; it does not guarantee that every call arrives. Retries are bounded, so a wide enough read can still come back throttled or time out. Narrow the read, honour any retry delay the vendor sends, and check whether a write landed before repeating it — see Retrying a failed or timed-out write.

Paused tenants still appear

A tenant you have paused in Petra is still returned by the tenant and usage tools, marked as paused. If you are counting clients, filter those out — otherwise your total will be higher than the number you are actually monitoring.

Two kinds of tenant ID

Petra tracks each client under both its own tenant ID and the Microsoft tenant ID. The incidents and failed-attacks tools accept either one. The billable-users tool accepts only Petra's own ID. The simplest habit is to start with the tenant list and use the IDs it hands back, rather than pasting an ID from somewhere else.

Plans and limits

Every Petra tool is read-only, so every one of them is available on the Free tier. There is nothing here that writes, so nothing moves to Pro. Business reaches the same tools and differs by monthly call quota.

See the generated Petra Security tool reference for the current inventory, plan assignment and input schemas.

Troubleshooting

"Petra Security rejected the API key" — the key is wrong, or it was deleted. Petra keys have no expiry and nothing renews on a schedule, so a key that worked yesterday and fails today has almost certainly been deleted in the portal. Deletion is immediate and cannot be undone. Mint a new key as an Admin, paste it into StackJack, and run a Test Connection.

"Petra Security denied the request" — this one has two quite different causes, and the error message tells you which. The common one is tenant scope: you asked about a client that is not in your Petra organization. Run the tenant list tool and use an ID from it. Petra keys are organization-scoped, so a key belonging to a different Petra organization cannot see your clients no matter how the request is written.

Test Connection is denied, but the key is definitely current — this is the OTHER cause of a denial, and on a connection test it is the only one that can apply, because that check reads your tenant list and names no client. Petra can refuse a request that reaches it without a browser-style identifying header, and StackJack always sends one, so something on the path between us and Petra removed or rewrote it: a proxy, a filtering gateway or a web firewall. Ask whoever runs that equipment to let the header through. StackJack reports this as a temporary condition and keeps the connection enabled, so nothing is switched off while you sort it out.

A client is refused on one tool but not another — this is the same tenant-scope problem wearing a different hat. Petra reports an unknown tenant as "not found" on the incidents and failed-attacks tools, but as "denied" on billable users. Both mean the tenant is not in your organization. Also check which ID you used: billable users accepts only Petra's own tenant ID, not the Microsoft one.

"Petra Security is rate-limiting requests" — you asked for too much too quickly on one endpoint. This is temporary and StackJack recovers on its own. If it keeps happening, you are probably fanning out a one-client-per-call tool across many clients. Switch to the usage tool for billing counts, and leave the tenant blank on incidents to cover everyone in one request.

A client shows no incidents at all — that is good news rather than a fault, but confirm the client is actually being monitored before you report it as a clean month. A paused tenant returns nothing, and the tenant list will tell you whether it is paused.

Your tenant count looks too high — paused tenants are included in both the tenant list and the usage report. Filter on the paused flag before counting.

Petra Security tools

petra_ · 5 tools · Free 5

Security Events

Tenants & Billing