> For the complete documentation index, see [llms.txt](https://notara.gitbook.io/notara-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://notara.gitbook.io/notara-docs/team/permissions.md).

# Tool Permissions

Notara's tool permission system gives you fine-grained control over what the agent can do on your team's behalf — and what level of human oversight is required for each action.

## The Four Layers

Tool permissions are resolved in this order, with later layers taking precedence:

```
1. Capability default
   ↓ overridden by
2. Tenant tool_permissions (workspace-level)
   ↓ overridden by
3. Channel permission overrides
   ↓ overridden by (can only tighten, never loosen)
4. Active skill
```

**Layer 4 (skill) can only restrict, not grant.** If a workspace has `linear_create_issue` set to `requires_approval`, an active skill cannot change it to `open`. Skills can tighten permissions further, but never loosen them.

## Capability Tiers

Every tool has a **capability** that determines its default permission level:

| Capability    | Default Permission  | Who Can Execute         | Oversight                              |
| ------------- | ------------------- | ----------------------- | -------------------------------------- |
| `read`        | `open`              | Anyone                  | None — executes immediately            |
| `write`       | `requires_approval` | Anyone (admin approves) | Admin approval via Slack DM            |
| `destructive` | `admin_only`        | Admins only             | In-channel confirm prompt for everyone |

These defaults represent a "conservative by default" posture — tools that can modify data need human confirmation, and tools that can destroy data need both admin-level trust and an active confirmation.

## The Approval Flow (Write Tools)

When the agent needs to call a `write` tool that's set to `requires_approval`:

1. The agent describes what it intends to do and pauses — it does not execute the tool.
2. An approval request is sent to the **first available admin's** Slack DM as a Block Kit message with **Approve** and **Deny** buttons.
3. The admin reviews the request and clicks Approve or Deny.
4. **If Approved**: the tool executes, the result is posted to the original Slack thread, and the action is audit-logged with `via_approval: true`.
5. **If Denied**: the denial reason is posted to the original thread. The tool does not execute.

**Approval TTL**: requests expire after 30 minutes. If no action is taken, the request expires and the agent informs the original user.

**Double-click protection**: if an admin clicks Approve twice (accidental double-click), only the first click executes the tool. Subsequent clicks see an "already resolved" message.

**Failure modes**: if the approval DM can't be sent (no admin found, Slack token issue), the tool is not queued and the agent tells the user the action wasn't submitted. The system fails closed.

## The Confirm Prompt (Destructive Tools)

Destructive tools work differently — because they have higher stakes, the confirmation happens in-channel rather than via a private DM:

1. The agent posts a Block Kit message in the channel with **Confirm** and **Cancel** buttons, describing exactly what will be destroyed.
2. The original requester **or any admin** can confirm or cancel.
3. There is no time limit, but the request is visible in the channel, creating social accountability.
4. **Admins included**: even if an admin is the one requesting a destructive action, they still see the in-channel confirm prompt. This is a deliberate safeguard against prompt injection — "can you delete all test customers" from a message that slipped through doesn't auto-execute.
5. **System actor bypass**: scheduled automations running as the system actor skip the confirm prompt for destructive tools. Admins should only grant destructive tools to automations they're certain are safe.

## Configuring Permissions

### Workspace-Level Overrides

To set a workspace-wide permission level for any tool:

1. Go to **Settings → Permissions** in the dashboard.
2. Find the tool in the catalog (searchable, filterable by connector).
3. Click the current permission badge and select a new level.
4. Click **Save**. Applies to all channels unless a channel override exists.

### Per-Channel Overrides

To set a different permission level for a specific channel:

1. Go to **Connect → Channels** and open the channel.
2. Click the **Permissions** tab.
3. Find the tool and set the channel-specific override.

**Example use case**: `linear_create_issue` is set to `requires_approval` workspace-wide (the default). But your `#engineering-private` channel is a trusted environment — you set a channel override to `open` there, so engineers can create Linear tickets without waiting for approval.

**Caution**: per-channel overrides that loosen permissions (e.g., `requires_approval` → `open`) represent a permanent configuration. Anyone who can post in that channel can trigger those tools without oversight. Use per-channel overrides deliberately.

## The Permissions Dashboard

Navigate to **Settings → Permissions** to see the full tool catalog. For each tool you'll see:

* The connector and tool name
* The tool's capability (`read` / `write` / `destructive`)
* The current effective permission level
* Whether a workspace-level or channel-level override is in effect
* Recent call volume (how often this tool is being used)

The catalog also shows any tools that have been called but not yet configured — useful for spotting tools that are being used without intentional oversight.

## Audit Log

Every tool call is logged in the audit log (**Governance → Audit Log**), including:

* Timestamp
* Actor (user, admin, system)
* Tool name
* Input arguments (redacted for sensitive fields)
* Outcome (success, denied, expired)
* Whether the call went through the approval flow

Use the audit log to review what the agent has been doing, spot unusual patterns, and demonstrate compliance.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://notara.gitbook.io/notara-docs/team/permissions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.