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

# SaaS Alerts API

> Investigate SaaS Alerts alert tickets: find the event, the user's other activity, the account and the client; manage suppressions, approved locations and Respond actions

The SaaS Alerts API tool gives Neo agents access to the SaaS Alerts Reports, Manage and Respond APIs. The common use is the alert ticket that SaaS Alerts writes in your PSA: the agent reads the event behind it, the user's other activity, the account and the client, and writes its verdict in an internal note.

<Info>
  Automatically enabled when you configure SaaS Alerts permissions in your agent workflow.
</Info>

## What It Does

* Find the event behind a SaaS Alerts ticket from its `Event ID`, with its severity, IP, location and operation
* Read the user's other events around the alert, and count how often the event type fires for the client
* Read the user's account (enabled or not, admin role) and the client's SaaS Alerts customer record and approved locations
* Read pending Respond rule triggers and the recommended actions
* Create, change or delete suppressions for one client or for named users of one client
* Set the approved countries, IP ranges and ASNs of a client or of named users, so activity from there stops raising alerts
* Run Respond actions on Microsoft 365 accounts (block sign-in, expire sessions, reset or force a password change, set up MFA, delete the user), and approve, reject, ignore or manually remediate a rule trigger
* Manage Respond rules, application connections, Unify devices, PSA mapping and scheduled reports

## How the agent handles an alert ticket

SaaS Alerts writes the ticket on the PSA company it maps to the SaaS Alerts customer. The body carries the `Event ID`, the user, the severity and a link with the SaaS Alerts customer id. The agent looks up the event by its id, reads the same user's events over a wider window, and checks whether the account is enabled and holds an admin role. It weighs the severity, the IP threat flags, the history and the recommended action, and writes what it found in an internal note. An alert on an anonymous SharePoint link (`urn:spo:tenantanon#...`) names no person, so the agent checks no account.

## Permission Groups

| Group | Access levels | Covers |
| - | - | - |
| Events and Alerts | Disabled, Read Only | Events, event search and counts, recommended actions, MFA and mailbox-rule reports |
| Customers and Users | Disabled, Read Only, Read / Write | SaaS Alerts customers, their users, the partner profile and billing; create, update or delete a customer |
| Approved Locations | Disabled, Read Only, Read / Write | Set the approved countries, IP ranges and ASNs for a client or for named users. The current lists are read from the customer record, which needs Customers and Users read access |
| Suppressions | Disabled, Read Only, Read / Write | Suppression rules; create, change or delete one |
| Respond Rules | Disabled, Read Only, Read / Write | Respond rules, rule templates, IOC rules and the Respond on/off state |
| Respond Triggers and Actions | Disabled, Read Only, Read / Write | Rule triggers and response-action jobs; trigger decisions and response actions |
| Connections and Devices | Disabled, Read Only, Read / Write | Respond organizations and application connections, Unify devices |
| PSA Mapping | Disabled, Read Only, Read / Write | The SaaS Alerts customer to PSA company mapping |
| Reports | Disabled, Read Only, Read / Write | Scheduled reports, report emails, report branding and uploaded report files |

## Access Profiles

| Profile | What runs on its own | What asks a technician |
| - | - | - |
| **Read Only** | Every read | No write is allowed |
| **Helpdesk** | Every read | Every write |
| **IT Admin** | Ignoring a rule trigger, customer changes, connections, devices and reports | Suppressions, approved locations, Respond rules and PSA mapping |
| **Full Automation** | Every write except those below | Only the writes below |

## Safety Controls

| Control | Behavior |
| - | - |
| **Response actions** | Every Respond action on a Microsoft 365 account always asks a technician |
| **Trigger decisions** | Approving, rejecting or manually remediating a rule trigger always asks a technician. Ignoring one follows the access profile |
| **Removals** | Deleting a customer, deleting an application connection and turning Respond off always ask a technician |
| **Suppression scope** | A suppression covers one client (customer scope) or named users of one client (users scope). Neo does not send a partner-scope suppression, which would cover every client |
| **Named accounts** | A response action must name each account it acts on |
| **Own events only** | An event search never names an Elasticsearch index, so it reads only your own SaaS Alerts events |
| **Refused** | Neo does not read or reset the partner API key, upload files, request a Respond access token, or call the event webhook services, which take a separate Webhooks API key |

## How to Configure

<Steps>
  <Step title="Connect SaaS Alerts">
    Save your partner API key in the Neo Dashboard under the **Security** integrations category. See [Connecting SaaS Alerts to Neo](/integrations/saas-alerts/connecting-to-neo).
  </Step>

  <Step title="Configure permissions">
    In your agent workflow's **Integrations** tab, choose an access profile or set each permission group by hand.
  </Step>
</Steps>

<Tip>
  Start with **Read Only**. Investigating an alert needs only reads in SaaS Alerts; the note on the ticket is written with the PSA tools.
</Tip>


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