> For the complete documentation index, see [llms.txt](https://docs.stoik.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stoik.io/human-security/permissions.md).
# Permissions
Human Security protects your people from phishing, fraud, and account compromise. To stop real threats and not only flag them, Stoïk needs a defined set of permissions in your Microsoft 365 or Google Workspace. This page explains every permission we request and what it does.
{% hint style="info" %}
**Our principles**
* **Least privilege:** we request only what a feature needs.
* **Purpose-bound:** every permission maps to a specific action, listed below.
* **Read first, act narrowly:** most access is read-only; writing is limited to protective actions.
* **Your data stays yours:** never sold, never used beyond the service you enabled.
* **Revocable anytime:** withdraw access from your admin console whenever you want.
{% endhint %}
## How access is structured
Human Security is built from three access blocks. Each feature uses only the blocks it needs, so you grant only what you enable.
* [Team directory access](#team-directory-access): read-only access to your employee list and groups. No mailbox access.
* [Mailbox protection](#mailbox-protection): mailbox access to deliver simulations, review reported emails, and act on confirmed threats.
* [Report button](#report-button): a lightweight add-in to flag suspicious emails. No mailbox access.
| Feature | Team directory access | Mailbox protection | Report button |
| ---------- | :-------------------: | :----------------: | :-----------: |
| Simulation | ✓ | ✓ | ✗ |
| Learning | ✓ | ✗ | ✗ |
| Report | ✓ | ✓ | ✓ |
{% hint style="success" %}
**You grant only what you use.** Learning needs read-only directory access and nothing else. Only Report also requires the add-in employees install.
{% endhint %}
## Team directory access
Read-only access to your employee list and groups, so Stoïk knows who to protect, simulate, and train. No mailbox access.
{% tabs %}
{% tab title="Microsoft 365" %}
| Permission | What it's for |
| ------------------------------------- | --------------------------------------------------------------------------------- |
| **User.Read.All** | Read users to build and update your employee list (names, emails, phone numbers). |
| **Group.Read.All** | Read groups so you can target and organize employees by team. |
| **UserAuthenticationMethod.Read.All** | Read employees' authentication (MFA) methods. |
| {% endtab %} | |
{% tab title="Google Workspace" %}
| Permission | What it's for |
| ---------------------------------- | ------------------------------------------------------------- |
| **admin.directory.user.readonly** | Read directory users to build and update your employee list. |
| **admin.directory.group.readonly** | Read groups so you can target and organize employees by team. |
| **userinfo.email** | Identify the administrator granting access. |
| {% endtab %} | |
| {% endtabs %} | |
## Mailbox protection
Mailbox access to deliver phishing simulations, read and analyse reported emails, and act on confirmed threats. You grant it when you connect your workspace for Simulation or Report.
{% tabs %}
{% tab title="Microsoft 365" %}
| Permission | What it's for |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User.Read.All** | Find users and match email addresses to mailboxes. |
| **Mail.ReadWrite** | Deliver phishing simulations (insert, read, clean up), read reported emails, and, soon, act on a confirmed threat: add or remove a warning banner, or move the email to and from a quarantine folder. |
| **SecurityAnalyzedMessage.Read.All** | Retrieve detection details for a reported email so we can tell your IT Manager whether it's a genuine threat (phishing or fraud). |
| **AuditLog.Read.All** · **AuditLogsQuery.Read.All** · **ActivityFeed.Read** | Detect malicious activity and confirm whether a reported email is a real threat or led to a compromise. |
| **MailboxSettings.Read** | Detect malicious mailbox rules, a common sign an email led to account takeover. |
| **UserAuthenticationMethod.Read.All** | Detect tampering with a user's MFA methods, and display MFA status. |
| **Policy.Read.ConditionalAccess** | Factor the account's protection posture into the threat assessment. |
| **Application.Read.All** | Detect malicious third-party apps connected to an account. |
| **Reports.Read.All** | Understand email volume and patterns, used to suggest the best targets for payment-fraud simulations (employees who receive the most invoices make the most realistic targets). |
| {% endtab %} | |
{% tab title="Google Workspace" %}
| Permission | What it's for |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **gmail.insert** | Insert phishing-simulation emails into mailboxes. |
| **gmail.metadata** | Read message headers and IDs to verify and track simulations. |
| **gmail.modify** | Move simulation setup-verification emails to Trash, and, soon, act on a confirmed threat (warning banner, quarantine). |
| **gmail.readonly** | Read the content of reported emails for review, and analyse the real invoice or payment emails employees receive to craft realistic payment-fraud simulations and pick the best targets. |
| **gmail.settings.basic** | Configure allowlisting so simulations reliably reach the inbox. |
| **admin.directory.user.readonly** | Match recipients to directory users. |
| **admin.reports.audit.readonly** | Detect suspicious activity to confirm whether a reported email is a real threat, and identify who receives the most invoices for payment-fraud targeting. |
| **apps.alerts** | Surface related Google Workspace security alerts when analysing a threat. |
| **admin.directory.customer.readonly** | Read organization details needed to configure protection. |
| **gmail.settings.sharing** | Read mailbox delegates, to spot access granted by a compromised account. |
| **admin.directory.device.mobile.readonly** | Read the mobile devices enrolled on an account, to spot an attacker's device. |
| {% endtab %} | |
| {% endtabs %} | |
{% hint style="info" %}
**How reported emails become a clear verdict.** When an employee reports an email, Stoïk analyses the message and the surrounding account and tenant signals to decide whether it's genuine phishing or fraud, so your IT Manager gets a reliable **true / false positive** verdict and can act on it directly.
{% endhint %}
## Report button
The add-in your employees use to flag suspicious emails. It is intentionally lightweight: it does not grant Stoïk any API access to your mailboxes.
{% tabs %}
{% tab title="Outlook add-in" %}
| Permission | What it's for |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| **ReadWriteMailbox** | Access the email being reported and, only if the user chooses, move it to Junk or Deleted Items. |
| **Report.Phishing** | Sign in to Stoïk's reporting API to submit the report. |
| {% endtab %} | |
{% tab title="Gmail extension (Chrome / Edge)" %}
| Permission | What it's for |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **identity** | Opens Google's sign-in to confirm which user is reporting. |
| **storage** | Temporarily caches the sign-in token and remembers the account email, to avoid repeated sign-in prompts. |
| **`mail.google.com` (site access)** | Adds the *Report to Stoïk* button in Gmail, identifies the open message and account, and uses Gmail's own controls for the resulting action. This is browser page access, not a Gmail API OAuth scope. |
| **`accounts.google.com` (site access)** | Supports Google sign-in. |
| **`*.phishing.cyber.stoik.io` (site access)** | Sends the report to Stoïk's API. |
| **Sign-in scopes: `openid`, `email`** | Signs the user in and identifies them by email. |
| {% endtab %} | |
| {% endtabs %} | |
{% hint style="success" %}
**The Gmail extension requests no mailbox OAuth scope.** Sign-in is limited to your identity (`openid` + `email`). Site access lets the extension act on the Gmail page you have open; it is not standing server-side access to your inbox.
{% endhint %}
## Common questions
Do you read all of our emails?
No. We deliver simulation emails and read the specific messages your employees report. Any continuous analysis runs only to detect threats, and only for the capabilities you enable.
Can we grant only some capabilities?
Yes. Permissions are grouped by capability. If you do not enable a capability, you do not grant its permissions.
Can we revoke access later?
Yes, at any time, from your Microsoft 365 or Google Workspace admin console. Revoking access stops the corresponding capability.
Why do some permissions allow writing, not only reading?
Protecting your team requires acting on threats, not only seeing them: delivering a simulation, moving a reported email, or quarantining a confirmed attack. Write access is limited to these actions.
---
# 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.stoik.io/human-security/permissions.md?ask=&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.